Authentication

OAuth 2.0 Flow Overview

The authentication process involves redirecting users to authorize your application, receiving an authorization code, then exchanging that code for access and refresh tokens.

✅

API access in 3 steps

1. User Authorization via https://connect.digits.com/v1/oauth/authorize
2. Token Exchange via https://connect.digits.com/v1/oauth/token
3. API calls with the app's access token

1. User Authorization

First, redirect users to the authorization endpoint to obtain an authorization code:

Authorization URL: https://connect.digits.com/v1/oauth/authorize

Query Parameters:

• response_type=code (required)
• client_id - Your app's Client ID
• redirect_uri - Must exactly match your registered redirect URI
• scope - Space-separated scopes (e.g., "source:sync ledger:read documents:write")
• state - Random string to prevent CSRF attacks (recommended)

Example Authorization URL:

https://connect.digits.com/v1/oauth/authorize?response_type=code
&client_id=<your_client_id_here>
&redirect_uri=<valid_redirect_url>
&scope=source%3Async%20ledger%3Aread%20documents%3Awrite
&state=<random_state_string>

After the user authorizes your application, they will be redirected to your redirect_uri with the authorization code:

https://yourapp.com/oauth/callback?code=base64_encoded_authorization_code&state=random_state_string

2. Authorization Code Exchange

Exchange your authorization code for access and refresh tokens using the token endpoint:

Endpoint: POST https://connect.digits.com/v1/oauth/token

Request Headers:

Content-Type: application/json

Request Body:

{
  "grantType": "authorization_code",
  "clientId": "your_client_id_here",
  "clientSecret": "your_client_secret_here", 
  "code": "base64_encoded_authorization_code",
  "redirectUri": "https://yourapp.com/oauth/callback"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_string_here",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "scope": "source:sync ledger:read documents:write"
}

3. Using Access Tokens

Include the access token in the Authorization header for all API requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example API Request:

curl -X GET https://connect.digits.com/v1/ledger/categories \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Scopes

Your access token includes specific scopes that determine which API operations are permitted:

• source:sync - Write ledger data to Digits
• ledger:read - Read ledger data from Digits
• documents:write - Upload and manage documents

Token Management

Token Expiration

Access tokens expire after 3600 seconds (1 hour). When a token expires, you'll receive a 401 Unauthorized response.

Refresh Tokens

Use refresh tokens to obtain new access tokens without requiring user re-authorization. Refresh tokens don't expire, but they are revoked if the user uninstalls your App.

Endpoint: POST https://connect.digits.com/v1/oauth/token

Request Headers:

Content-Type: application/json

Request Body:

{
  "grantType": "refresh_token",
  "clientId": "your_client_id_here",
  "clientSecret": "your_client_secret_here",
  "refreshToken": "your_refresh_token_here"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "new_refresh_token_string_here",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "scope": "source:sync ledger:read documents:write"
}

The response includes a new access token and a new refresh token. Store the new refresh token for future token refreshes.

Error Handling

Common authentication errors include:

• Authorization code already used: Each authorization code can only be exchanged once
• Authorization code expired: Codes have a limited lifetime
• Invalid client credentials: Check your clientId and clientSecret
• Redirect URI mismatch: Must exactly match the registered redirect URI

Security Considerations

• Authorization codes are base64-encoded strings containing a unique identifier and cryptographic secret
• All API requests must use HTTPS
• Store client secrets securely and never expose them in client-side code
• Redirect URIs are validated to prevent authorization code interception