OAuth

If you want to enable a 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.

On This Page

Request API Credentials

Getting 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. To create the credentials, August needs these from you:

  1. Your GPG/PGP public key so that August can encrypt the credentials to send to you.
  2. At least one redirect URL (you can give several). This URL must support TLS.
  3. A URL for your icon, 220x220 pixels, e.g.

August Icon

Send these three items via email to devsupport@august.com

August will then reply to your email with the following data, encrypted with your public key:

  1. client_id, a character string to identify your company in Step 1 below.
  2. client_secret is like a password for your company, which you will use in Step 4 below.
  3. x-august-api-key which you will use in a header of your REST calls (after you've completed the OAuth process).

Getting 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 two grant types.

  • Authorization code - Use this grant type to get an access token for one of your users.
  • Client credentials - Use this grant type to get an access token for an account that you own.

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
FieldExample ValueSource
client_id1234-5678-abcdAugust gave this to you when you requested API credentials. This is a client id which will identifies you to the API.
redirect_urihttps%3A%2F%2Fexample.com%2FcallbackYou 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.
statefrom%20you%20to%20youThis 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.

  1. The user must log in with their previously-verified email address and password.

    Sign in to August
  2. Then we send an SMS text message to their previously-verified mobile phone.

    Verify Phone Number
  3. 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.

    Authorizing the 3rd Party App

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:

Step 4: You get an access token from the 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:

ParameterExampleSource
client_id1234-5678-abcdAugust gave this to you in step 1. This is a client id which will identify you to our service.
client_secret1234%2FabcdABCD%3DAugust gave this to you in step 1
codeac8675309The code you received in the previous step.
grant_typeauthorization_codeWe only support authorization_code and client_credentials.

❗ 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"
}

Client Credentials

Use the client credentials grant type to get an access token for an account that you own.

Permission Required

By default, API credentials cannot use this grant type. Contact August so we can give you permission.

curl -X POST \
     --data-urlencode "client_id=$CLIENTID" \
     --data-urlencode "client_secret=$CLIENTSECRET" \
     --data-urlencode "grant_type=client_credentials" \
     https://auth.august.com/access_token

The response will be the same as the response using the authorization code grant type.

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 "&":

  1. curl -v -X GET https://auth.august.com/access_token?client_id=111-222-333-444-555 (running as process 7748)
  2. client_secret=SEEECRET (running as process 8868 above)
  3. grant_type=authorization_code (running as process 8888 above)
  4. 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!