Access Tokens#

If you want to enable your user to authorize you to make August API requests on their behalf, your user will have to go through the following OAuth steps. Your application will not create any August user accounts. Instead, August follows OAuth2 for authentication and authorization so that existing users can give you permission to do things for them via the August API.

If you're not familiar with OAuth2, An Introduction to OAuth 2 | DigitalOcean gives a good overview.

Generate API Credentials#

Generating API credentials is the first thing you need to do. You'll use these when you send a user to the August OAuth server to log in.

First go to the developer portal and click "Manage".

Click "Manage credentials", then "Add credential".

![one](media/create-api-credentials-1.png)

Then fill out the form.

![two](media/create-api-credentials-2.png)

API credentials consist of the information you put into the form, plus the following things.

Client ID is a unique identifier that identifies you to the August API. It is referred to as client_id in code samples. Use it in step 1 below.
Client secret is like a password. It is referred to as client_secret in code samples. Use it in step 4 below.
API key is another unique identifier that identifies you to the August API. When making API calls, use it as the value of the x-august-api-key header.

Get an Access Token#

Once you have API credentials, you can start getting access tokens for yourself and/or your users.

Grant Types#

The API supports the authorization code grant type.

Authorization Code#

These are the steps for getting an access token for one of your users.

Step 1: You direct the user to the August OAuth server#

This can happen in a browser or a web view in a mobile app.

GET https://auth.august.com/authorization?client_id=1234-5678-abcd&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&state=from%20you%20to%20you

Query Strings
Field	Example Value	Source
`client_id`	`1234-5678-abcd`	The client ID for your API credentials.
`redirect_uri`	`https%3A%2F%2Fexample.com%2Fcallback`	You gave this to August when you requested API credentials. This is the url for your confidential OAuth client, a server to which we send an authorization code once the user has completed the authorization and verification steps.
`state`	`from%20you%20to%20you`	This is generated by you at the time of the request. It will be sent back to you at the end of the OAuth process. Typically it is used to guard against CSRF.

💡 Remember to url-encode these strings since you're sending them as part of the URL.

Step 2: The user authenticates to August and authorizes your access#

Note: There is no work for you to do here. This is the user interacting with August.

The user must log in with their previously-verified email address and password.
Then we send an SMS text message to their previously-verified mobile phone.
The August OAuth server (auth.august.com) presents the user with an overview of who is making the request (your app) and what they will be authorized to do if the user approves.

Step 3: The August OAuth server redirects the user back to you#

The August OAuth server responds with an HTTP 302 redirection, sending the user to the redirect_uri you provided in Step 1. This redirect_uri is a sever you control, protected with TLS, which can complete the OAuth process. The OAuth spec RFC 6749 calls your server a Confidential Client because it holds the client_secret and ensures that the user never sees the confidential access information.

In this step, you should check the state value to ensure that it is valid.

User Grants Permission#

If the user grants permission then the URL will look like this.

https://example.com/callback&code=ac8675309&state=from%20you%20to%20you

This request will contain two query parameters:

code: The authorization code we have generated which you will use in the next step.
state: The state as above.

User Cancels/Declines to Grant Permission#

If the user Cancels and does not authorize your application, then the August OAuth server will still redirect back to your application, but the URL will look like this.

https://example.com/callback?error=access_denied&state=from%20you%20to%20you

This request will contain two query parameters:

error: This error response is in conformance with the OAuth 2 specification.
state: The state as above.

Step 4: You get an access token from the August OAuth server.#

The access_token will be in the Response.

This is a server-to-server operation, from your Confidential Client to the August OAuth server. August is not entirely OAuth2-conformant here because we require the data to be in the POST body.

POST https://auth.august.com/access_token (data in POST body)

You must use application/x-www-form-urlencoded (as a header) and url-encode the body.

You must include the client_id and client_secret in the form-encoded data. Do not use Authorization: Basic to pass these values or you will get a 400 error "secrets did not match". If your OAuth framework/library requires you to send Basic Auth, you can use bogus values or the real client_id:client_secret and they will be ignored. The client_id and client_secret must be part of the form-encoded strings in the body.

cURL example:#

curl -X POST \
     --data-urlencode "client_id=YOUR CLIENT ID FROM STEP 0" \
     --data-urlencode "client_secret=YOUR CLIENT SECRET FROM STEP 0" \
     --data-urlencode "code=CODE RETURNED FROM STEP 2" \
     --data-urlencode "grant_type=authorization_code" \
     https://auth.august.com/access_token \
     --trace-ascii /dev/stdout

Mock example of data sent in body
=> Send data, 159 bytes (0x9f)
0000: client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET%3D
0040: &code=CODE
0080: &grant_type=authorization_code

Where:

Parameter	Example	Source
`client_id`	`1234-5678-abcd`	August gave this to you in step 1. This is a client ID which will identify you to our service.
`client_secret`	`1234%2FabcdABCD%3D`	August gave this to you in step 1
`code`	`ac8675309`	The code you received in the previous step.
`grant_type`	`authorization_code`	We only support authorization_code.

❗ Note about using cURL: Be sure to quote parameters that have ampersands in them (e.g. curl "https://example.com?p=1&q=2") or else parts of your command may be interpreted as background jobs in Unix systems. That can make your request fail with a 302 to /error.

💡 Remember to url-encode these strings in the body.

Response#

The final response will be a JSON object which contains the user’s OAuth access_token, which you will use to impersonate the user when accessing the API.

The access_token will expire expires_in seconds from now.

For more information about the refresh_token see the refresh tokens page.

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpbnN0YWxsSWQiOiIiLCJyZWdpb24iOiJpcmVsYW5kLXByb2QtYXdzIiwiYXBwbGljYXRpb25JZCI6IiIsInVzZXJJZCI6IjU0YzUzNmYzLTFjNTEtNGVhOC1iODIwLWFlODk3YTY2ZTg0ZSIsInZJbnN0YWxsSWQiOmZhbHNlLCJ2UaFzc3dvcmQiOnRydWUsInZFbWFpbCI6dHJ1ZSwidlBob25lIjp0cnVlLCJoYXNJbnN0YWxsSWQiOmZhbHNlLCJoYXNQYXNzd29yZCI6ZmFsc2UsImhhc0VtYWlsIjpmYWxzZSwiaGFzUGhvbmUiOmZhbHNlLCJpc0xvY2tlZE91dCI6ZmFsc2UsIm9hdXRoIjp7ImFwcF9uYW1lIjoiWmlsbG93IChTdGFnaW5nKSIsImNsaWVudF9pZCI6ImZmOGI4NWExLTU5NTEtNGRjYy04MDJiLTE4NmE5MTliODM2NSIsImFwadtleSI6Ijg2ODUzMmJhLWU0YzgtNDVjZS1hMDVmLTNmNjQzYTYwNjkwNiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vdHR2MDc0Y3U2ZC5leGVjdXRlLWFwaS51cy13ZXN0LTIuYW1hem9uYXdzLmNvbS9kZXYvYXV0aC9jYWxsYmFjayJ9LCJjYXB0Y2hhIjoiIiwiZW1haWwiOltdLCJwaG9uZSI6W10sImV4cGlyZXNBcCI6IjIwMjEtMTEtMjVUMjM6MDE6MzcuNjE1WiIsInRlbXBvcmFyeUFjY291bnRDcmVhdGlvblBhc3N3b3JkTGluayI6IiIsImlhdCI6MTYyNzUxMzI5NywiZXhwIjoxNjM3ODgxMjk3fQ.hWTjkU7huN_ssT5VloBO3UnxNbGBeWnaTAEbLQ6NLxU",
    "expires_in": 10367999,
    "refresh_token": "00f491c3ea3b043c590fbd0a7594fa47:812cc75d0e6238d261677481d7f9b4b0c00a16947635280bd24e3e4424390ca8"
}

OAuth is Complete#

Now that you have your access_token, you can use it to make calls to the August API:

curl -X GET \
    -H "x-august-api-key: <your api key>" \
    -H "x-august-access-token: <the accesstoken>" \
    -H "content-type: application/json" \
    https://api-production.august.com/users/locks/mine

💡 Note that you don't have to URL encode the parameters here since they are passed via headers.

Troubleshooting#

302 Errors#

Problem: You're seeing something like this:

$ curl -v -X GET https://auth.august.com/access_token?client_id=111-222-333-444-555&client_secret=SEEECRET&grant_type=authorization_code&code=SEECRETTOO
[1] 8868
[2] 8888
[3] 7748
[2] Done client_secret=SEEECRET
[3]+ Done grant_type=authorization_code

and your request fails in a 302 to error.

Cause: Some of your parameters are being interpreted by the unix commandline (bash usually) as background jobs. So it thinks you want to run 4 commands, separated by "&":

curl -v -X GET https://auth.august.com/access_token?client_id=111-222-333-444-555 (running as process 7748)
client_secret=SEEECRET (running as process 8868 above)
grant_type=authorization_code (running as process 8888 above)
code=SEECRETTOO (running in the foreground)

Fix: You need to quote the whole URL to force the bash commandline to interpret it as one parameter:

$ curl -v -X GET "https://auth.august.com/access_token?client_id=111-222-333-444-555&client_secret=SEEECRET&grant_type=authorization_code&code=SEECRETTOO"

💡 Another cause for a 302 /error can be using POST instead of GET when calling https://auth.august.com/access_token. Use GET!