Authorization Code Grant

Use the Authorization Code Grant to authenticate and authorize users

The Authorization Code Grant is a standard OAuth 2.0 flow that enables secure user authentication and authorization. This flow allows applications to obtain an access_token by first receiving an authorization code after the user logs in. The process works as follows:

1. Your application redirects the user to authenticate with their Smokeball credentials
2. Upon successful authentication, Smokeball returns an authorization code to your redirect URI
3. Your application exchanges this code for an access_token that can be used to make authenticated API requests

This is the recommended OAuth 2.0 flow when you need to access the Smokeball API on behalf of a specific user.

Request User Authorization

Direct the user to https://auth.smokeball.com/oauth2/authorize with the following parameters:

Example:

curl

curl -X GET 'https://auth.smokeball.com/oauth2/authorize?response_type=code&client_id=xxxxx&redirect_uri=https://xxxxxxxx&scope=contacts%2Fread%20matters%2Fread%20matters%2Fwrite'

response_type · string · required

Must be set to “code” for Authorization Code flow. Determines the OAuth 2.0 grant type being requested.

client_id · string · required

The client identifier issued during application registration. Used to identify the application making the authorization request.

redirect_uri · string · required

The URI where the authorization server will send the authorization code. Must match one of the pre-registered redirect URIs.

state · string

An opaque value used to maintain state between request and callback. Helps prevent CSRF attacks in the OAuth flow.

This parameter is optional.

scope · string · required

The scopes of access being requested, as a space-delimited list (for example contacts/read matters/read matters/write). Every scope requested must be assigned to your app in the Developer Console.

OAuth 2.0 expects a client to state the scopes it wants, so always include this parameter. The install URL shown on your app’s page in the Developer Console already includes every scope assigned to the app, sorted alphabetically, and updates as scopes are added or removed. If the parameter is omitted the authorization server currently falls back to issuing a token with all scopes assigned to the app, but you should not rely on this behaviour.

The user will be directed to a login page where they will need to use their Smokeball credentials to login.

If authorized, the user will be redirected to:

https://your_redirect_uri?code=xxxxx

The response returns a one time use code that is valid for five minutes.

See AWS Cognito Authorization Endpoint Documentation for more information.

Request an Access Token

Once you have obtained an authorization code, you can now use it to get an access_token which may be used to make requests to the API.

Make a POST request to https://auth.smokeball.com/oauth2/token with the following parameters and headers:

curl

curl --request POST \
  --url https://auth.smokeball.com/oauth2/token \
  --header "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=xxxx" \
  --data-urlencode "redirect_uri=https://xxxxx" \
  --data-urlencode "code=the code acquired from step 1"

The Authorization header must be the string “Basic” followed by your client_id and client_secret with a colon : in between, Base64 Encoded. For example, client_id:client_secret is Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json

{ 
 "refresh_token":"dn43ud8uj32nk2je", 
 "access_token":"dmcxd329ujdmkemkd349r",
 "token_type":"Bearer", 
 "expires_in":3600
}

refresh_token · string

A token used to obtain a new access token when the current one expires.

By default, the returned refresh_token is valid for 180 days. If you require a longer expiration period, please contact us to discuss your specific needs.

The 180-day expiry took effect on 24 August 2026 and applies to refresh tokens issued on or after that date. Refresh tokens issued before then remain valid for 30 days.

access_token · string

The access token used to authenticate API requests.

By default, the returned access_token is valid for 60 minutes.

token_type · string

The type of token issued (typically "Bearer").

Indicates how the token should be presented in API requests.

expires_in · number

The lifetime of the access token in seconds.

After expiration, a new token must be obtained.

Important: The refresh token expiry is not returned in the above response. Your application is responsible for monitoring the expiration of the refresh token and prompting the user to re-authenticate when it expires. This ensures continuous access to the application without interruptions. See AWS Cognito Token Endpoint Documentation for more information

The use of id_token to make API requests has been deprecated. API requests can now also be made using the access_token.

For further information, see migration section below for migrating from id_token to access_token.

Please note that the id_token will continue to work for the time being and no immediate action is required.

PKCE (Proof Key for Code Exchange)

PKCE is an extension of the Authorization Code Grant flow, designed for mobile and single-page applications where storing a client secret securely is difficult. It ensures a more secure flow by requiring a dynamically generated code verifier and code challenge. It is recommended that all authorization code flows are authorized using PKCE and it is required for all public api clients, which do not have a client secret.

Generate a Code Verifier and Code Challenge

To initiate the PKCE flow, you must generate a code_verifier, which is a random string, and a code_challenge, which is derived by hashing the code_verifier using SHA-256 and then Base64-URL encoding it.

c#

using System;
using System.Security.Cryptography;
using System.Text;

class PKCEGenerator
{
    public static void Main()
    {
        string codeVerifier = GenerateCodeVerifier();
        string codeChallenge = GenerateCodeChallenge(codeVerifier);

        Console.WriteLine("Code Verifier: " + codeVerifier);
        Console.WriteLine("Code Challenge: " + codeChallenge);
    }

    // Generate a random code verifier
    private static string GenerateCodeVerifier()
    {
        var randomBytes = new byte[32]; // 32-byte random string
        using (var rng = RandomNumberGenerator.Create())
        {
            rng.GetBytes(randomBytes);
        }
        return Base64UrlEncode(randomBytes);
    }

    // Create code challenge using SHA256
    private static string GenerateCodeChallenge(string codeVerifier)
    {
        using (var sha256 = SHA256.Create())
        {
            byte[] challengeBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(codeVerifier));
            return Base64UrlEncode(challengeBytes);
        }
    }

    // Base64 URL Encoding (removes padding, uses '-' and '_')
    private static string Base64UrlEncode(byte[] bytes)
    {
        return Convert.ToBase64String(bytes)
            .Replace("+", "-")
            .Replace("/", "_")
            .TrimEnd('=');
    }
}

Request Authorization Code for Access Token

Direct the user to https://auth.smokeball.com/oauth2/authorize with the following parameters:

curl

curl --request GET \
  --url "https://auth.smokeball.com/oauth2/authorize?response_type=code&client_id=xxxxx&redirect_uri=https://your_redirect_uri&scope=contacts%2Fread%20matters%2Fread%20matters%2Fwrite&code_challenge_method=S256&code_challenge=your_code_challenge"

response_type · string · required

Must be set to “code” for Authorization Code flow.

Determines the OAuth 2.0 grant type being requested.

client_id · string · required

The client identifier issued during application registration.

Used to identify the application making the authorization request.

redirect_uri · string · required

The URI where the authorization server will send the authorization code.

Must match one of the pre-registered redirect URIs.

code_challenge · string · required

The PKCE code challenge derived from the code verifier.

Generated using the S256 code challenge method.

code_challenge_method · string · required

The hash method used to generate the code challenge (must be “S256”).

Ensures secure PKCE implementation for authorization flow.

state · string

An opaque value used to maintain state between request and callback.

Helps prevent CSRF attacks in the OAuth flow.

This parameter is optional.

scope · string · required

The scopes of access being requested, as a space-delimited list (for example contacts/read matters/read matters/write). Every scope requested must be assigned to your app in the Developer Console.

OAuth 2.0 expects a client to state the scopes it wants, so always include this parameter. The install URL shown on your app’s page in the Developer Console already includes every scope assigned to the app, sorted alphabetically, and updates as scopes are added or removed. If the parameter is omitted the authorization server currently falls back to issuing a token with all scopes assigned to the app, but you should not rely on this behaviour.

For Smokeball API, only S256 method is allowed for code_challenge_method

The user will be directed to the login page, and if authorized, redirected back with a code.

Exchange Authorization Code for Access Token

After receiving the authorization code, use it along with the code_verifier to request an access token:

curl

curl --request POST \
  --url https://auth.smokeball.com/oauth2/token \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=xxxxx" \
  --data-urlencode "code=authorization_code_from_previous_step" \
  --data-urlencode "redirect_uri=https://your_redirect_uri" \
  --data-urlencode "code_verifier=your_code_verifier"

grant_type · string · required

Must be set to “authorization_code” for this flow.

Specifies the OAuth 2.0 grant type being used.

client_id · string · required

The client identifier issued during application registration.

Must match the client_id used in the authorization request.

code · string · required

The authorization code received from the authorization server.

This is the code obtained in the previous authorization step.

redirect_uri · string · required

The same redirect URI that was used in the authorization request.

Must exactly match the previous URI for security validation.

code_verifier · string · required

The original PKCE code verifier that was used to generate the code_challenge.

Used to prove possession of the authorization code.

client_secret · string · required

The client secret for confidential clients.

Required if the client is configured with a secret.

You will receive an access token that can be used to authenticate API requests.

Refreshing an Access Token

You can use the refresh_token returned in the previous request to continuously retrieve a valid access_token for use with the API. To exchange a refresh_token for an access_token, make the following request:

curl

  curl -X POST 'https://auth.smokeball.com/oauth2/token' \
    --header 'Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=refresh_token' \
    --data-urlencode 'client_id=xxxxxx' \
    --data-urlencode 'refresh_token=xxxxxx'

Authorization · string · required

Basic Authentication header containing base64-encoded client_id:client_secret.

Example: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Content-Type · string · required

Must be application/x-www-form-urlencoded for token endpoints.

grant_type · string · required

Must be refresh_token for this flow.

Determines the OAuth 2.0 grant type being used.

client_id · string · required

The client identifier issued during registration.

Must match the client ID used in the Basic Auth header.

refresh_token · string · required

Previously issued refresh token.

Used to obtain new access tokens without re-authentication.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "access_token":"dmcxd329ujdmkemkd349r",
 "token_type":"Bearer", 
 "expires_in":3600
}

access_token · string · required

The access token used to authenticate API requests.

By default, the returned access_token is valid for 60 minutes.

token_type · string · required

The type of token issued (typically "Bearer").

Indicates how the token should be presented in API requests.

expires_in · number · required

The lifetime of the access token in seconds.

After expiration, a new token must be obtained.

See AWS Cognito User Pool OAuth 2.0 Grants for more information

Migrating from ID Tokens to Access Tokens

Using ID tokens (id_token) to make Smokeball API requests is deprecated. If your integration currently uses ID tokens for API requests, you must switch to access tokens (access_token) before December 2026.

What is changing?

Existing refresh tokens and ID tokens will continue to work, subject to their normal expiry and revocation conditions. However, for accounts connecting to your integration from December 2026 onwards, newly issued ID tokens may no longer be accepted for API requests.

Complete the switch before December 2026 to avoid disruption for these accounts.

How to migrate

1. Confirm your API scopes. Access tokens must include the permissions required by your integration. Review the scopes documentation and identify only the API scopes your integration needs.

   • If your integration already has the required API scopes configured, you can proceed with the migration.
   • If your scopes have not been configured, or you are unsure, contact us using the API scope request form. Provide your required scopes, or a list of the API endpoints and HTTP methods you use, so we can confirm the necessary permissions before you switch.

2. Update your authorisation requests if you explicitly pass a scope query parameter. If your requests to https://auth.smokeball.com/oauth2/authorize include scope, ensure it lists only the API scopes your integration requires, such as matters/read, and remove openid. If you do not pass a scope parameter, no change is required for this step.

3. Use the access token for API requests. Update your integration to use the access_token returned by the token endpoint instead of the id_token.

4. Test your integration. Confirm that your API requests work with access tokens and that the configured scopes cover all required functionality. Contact us if you encounter permission issues.

Important: Existing connections continuing to work does not mean your integration is ready for new connections from December 2026. Complete and test the switch to access tokens before then.