1. Obtain Authorisation Code

First, you will need to redirect the user to Capsule to grant access to your application:

Response

Capsule will display a page asking the user to approve or deny access to your application. However, if you provided an invalid client_id or redirect_uri the user will instead see an error page.

2. Capsule redirects back to your site

After the user approves your application, Capsule will redirect to the URL provided in the request with a temporary code in the code parameter as well as the state you provided in the previous step in the state parameter. To protect against CSRF attacks, you must check if the value of the state is same as the one you provided in the first step.

If the user denies the access request or if the request fails, the user will be redirected to your application with an error and error_description parameter. The exact values of the error parameter can be found in section 4.1.2.1 of RFC6749.

3. Exchange the code for an access and refresh token.

Once you have obtained an authorization code, you can exchange it for an access and refresh token. The body of the request should be valid JSON or x-www-form-urlencoded.

{
    "code": "5lkdysut02m4z7kstxgy5zl1xy70qbc6e3nhmps3oo0gbh3uz7",
    "client_id": "1ng7irbzhvmqe",
    "client_secret": "2rw6x7b1r9whd3ayxuzruv91zyxyubp28m6vdo2qmf9pn0qhsr",
    "grant_type": "authorization_code"
}

Parameters

Response

The server response will contain a JSON object with the access and refresh token, the granted scope, the token type (which is always bearer), the expiration time of the access token, and the subdomain of the user's Capsule account.

In case of and invalid request, Capsule will respond with an HTTP 400 (Bad Request) status code and include an error and error_description parameter in the response. These parameters are defined in section 5.2 of RFC 6749.

{
    "refresh_token":"68hpw0l714stokog519t4yi8tamlb53494n93vvz3v6xw3zbkw",
    "access_token":"2dkduvodqxm2npzypf75x1cctn77592hv4l3hf8nnxh6r4gjl8",
    "expires_in":604799,
    "token_type":"bearer",
    "scope":"read write",
    "subdomain": "exampleco"
}

4. Use the access token to access the API

The access token allows you to make requests to the API on behalf of a user by including it in the Authorization header: Authorization: Bearer access_token. More details are included in the Authentication section.

5. Refresh access token

After the access token expires, you will not the able to use it to make API requests. However, you can use the refresh token to obtain a new access token. The body of the request should be valid JSON or x-www-form-urlencoded.

{
    "client_id": "1ng7irbzhvmqe",
    "client_secret": "2rw6x7b1r9whd3ayxuzruv91zyxyubp28m6vdo2qmf9pn0qhsr",
    "refresh_token": "68hpw0l714stokog519t4yi8tamlb53494n93vvz3v6xw3zbkw",
    "grant_type": "refresh_token"
}

Parameters

Response

The response is the same as the response from step 3. It will contain a JSON object with the access and refresh token, the granted scope, the token type (which is always bearer), the expiration time of the access token, and the subdomain of the user's Capsule account.

Note that you might receive a new refresh token as part of the response. In this case you must discard the old refresh token and replace it with the new refresh token.

In the case of an invalid request, Capsule will respond with an HTTP 400 (Bad Request) status code and includes an error and error_description parameter in the response. These parameters are defined in section 5.2 of RFC 6749.

{
    "refresh_token":"68hpw0l714stokog519t4yi8tamlb53494n93vvz3v6xw3zbkw",
    "access_token":"2dkduvodqxm2npzypf75x1cctn77592hv4l3hf8nnxh6r4gjl8",
    "expires_in":604799,
    "token_type":"bearer",
    "scope":"read write",
    "subdomain": "exampleco"
}

6. Revoking a token

We encourage OAuth2 clients to revoke tokens when they are no longer needed. This is useful for ensuring that tokens, if stolen, aren't usable, and just for acting as a good citizen when the user "logs out" of your application (as an example).

Revoking a refresh token will also revoke any associated access tokens and remove the application from the list of authorised applications in Capsule. This step should be performed when a user chooses to disable an integration with Capsule to make it clear that the application is fully disconnected.

When your client is completely done with a token and will not use it anymore, it can make a POST request to revoke the token. The body of the request should be valid JSON or x-www-form-urlencoded and contain a token parameter.

{
    "token": "68hpw0l714stokog519t4yi8tamlb53494n93vvz3v6xw3zbkw"
}

Parameters

To be fully compatible with RFC 7009 Capsule will also accept the token_type_hint parameter, however the presence or value of this parameter will not affect the end result of your request.

Common errors during the authorization request

There are a few things that can go wrong in the process of obtaining an OAuth token for a user. If an error occurs, the response body or URL will include error and error_description parameters. Additionally, when possible, the status code of the response will be HTTP 400 Bad Request.

Redirect URI mismatch

If you provide a redirect_uri that doesn't match what you've registered with your application, Capsule will display an error page to the user and not redirect to the registered callback URL.

To correct this error, either provide a redirect_uri that matches what you registered or leave out this parameter to use the default value registered with your application.

Access denied

If the user rejects access to your application, Capsule will redirect to the registered callback URL with error and error_description parameters summarizing the error:

https://client.example.com/cb?error=access_denied&state=xyz&error_description=User%20denied%20access%20to%20your%20application"

There's nothing you can do here as users are free to choose not to provide access to your application.

Incorrect client credentials

If the client_id and or client_secret you pass are incorrect you will receive this error response.

{
    "error":"invalid_client",
    "error_description":"no client found with provided key and secret"
}

To resolve this error, make sure you have included the correct credentials for your application.

Redirect URI mismatch(2)

When exchanging the authorization code for an access token you must provide the same redirect_uri used to obtain the code. If these do not match, you will receive this error message:

{
    "error":"invalid_request",
    "error_description":"invalid redirect_uri"
}

To resolve this error, make sure that you provide the same redirect_uri at both steps of the OAuth 2 flow.

Bad authorisation code

If the authorization code is invalid, expired or already used, you will receive this error:

{
    "error":"invalid_grant",
    "error_description":"incorrect authorization code"
}

To resolve this error, start the OAuth process over from the beginning to obtain a new authorisation code.