OAuth Bearer Token Authentication

Overview

BlueClerk's OAuth 2.0 implementation lets third-party applications authenticate API requests using bearer tokens. After completing the authorization flow and exchanging an authorization code for an access token, clients include the token in the Authorization header of each API request. The system automatically enforces test client isolation to prevent test tokens from accessing production data.

How Authentication Works

Making Authenticated Requests

After obtaining an access token from the token endpoint:

1. Include the token in the Authorization header of your API request
2. Format: Authorization: Bearer YOUR_ACCESS_TOKEN
3. BlueClerk verifies the token and extracts user context
4. Your request is processed with the authenticated user's permissions

Example Request

curl -X GET https://app.blueclerk.com/api/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Authorization Flow

Step 1: User Consent

Users visit the authorization URL with your client credentials:

GET /oauth/authorize?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=read_customers
  &state=RANDOM_STRING
  &code_challenge=YOUR_PKCE_CHALLENGE
  &code_challenge_method=S256

The user sees a consent screen where they:

• Review requested permissions - What data your app wants to access
• Choose which company to connect - If they belong to multiple companies
• Click Allow or Deny - Grant or reject access

Step 2: Authorization Code

After the user clicks Allow, BlueClerk redirects back to your redirect_uri with an authorization code:

https://yourapp.com/callback?code=AUTH_CODE&state=RANDOM_STRING

The authorization code:

• Expires in 10 minutes
• Can only be used once
• Must be exchanged for an access token

Step 3: Token Exchange

Exchange the authorization code for an access token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&code_verifier=YOUR_PKCE_VERIFIER

Response:

{
  "access_token": "at_...",
  "refresh_token": "rt_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read_customers"
}

Step 4: Use Access Token

Include the access token in API requests:

curl -X GET https://app.blueclerk.com/api/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Step 5: Refresh Tokens

When your access token expires, use the refresh token to get a new one:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID

Token Security

Access Token Expiration

• Access tokens expire in 1 hour (3600 seconds)
• Refresh tokens expire in 90 days
• Use refresh tokens to get new access tokens without re-authorizing

Token Revocation

Revoke tokens when users disconnect your app:

POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=YOUR_ACCESS_TOKEN
&client_id=YOUR_CLIENT_ID

This invalidates both the access token and its associated refresh token.

Test Client Isolation

How It Works

Test OAuth clients (marked with isTestClient: true) can only access test data:

• Test tokens can only access companies marked isInternal: true
• Production companies are invisible to test client tokens
• Authorization fails if a test client tries to connect a production company
• Automatic enforcement - no manual checks needed

Creating Test Clients

Contact BlueClerk support to create a test OAuth client for development. Test clients let you:

• Develop integrations safely without touching production data
• Test authorization flows end-to-end
• Verify token handling and refresh logic

Available Endpoints

User Information

GET /api/v1/me
Authorization: Bearer YOUR_ACCESS_TOKEN

Returns the authenticated user's profile and company information.

More Endpoints

Additional API endpoints depend on the scopes you've requested. See the OAuth Scopes documentation for details on what each scope enables.

Error Handling

Invalid Token

{
  "error": "invalid_token",
  "error_description": "Token has expired or is invalid"
}

Solution: Use your refresh token to get a new access token.

Insufficient Scope

{
  "error": "insufficient_scope",
  "error_description": "Token does not have required scope"
}

Solution: Request the required scope during authorization.

Test Client Restriction

{
  "error": "test_client_prod_company",
  "error_description": "Test clients cannot access production companies"
}

Solution: Use a production OAuth client or test with an internal company.

Questions

Q: How long do access tokens last?
A: Access tokens expire after 1 hour. Use refresh tokens to get new access tokens without re-authorizing the user.

Q: Can I use one token for multiple companies?
A: No. Each authorization is specific to one user and one company. If a user belongs to multiple companies, they must authorize each company separately.

Q: What happens if I use a test client token on production data?
A: The API will return a 403 error with test_client_prod_company. Test clients are automatically restricted to internal test companies only.

Q: How do I revoke a user's access?
A: Call the /oauth/revoke endpoint with the user's access token. This invalidates both the access token and refresh token immediately.

Q: Do I need to implement PKCE?
A: Yes, for public clients (mobile apps, SPAs). PKCE prevents authorization code interception attacks. BlueClerk requires code_challenge and code_verifier parameters for all authorization flows.