Authentication

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

The Apiera API uses OAuth 2.0 with the client credentials flow. All requests must include a valid access token.

Overview

To access the API, you need:

1. Client credentials (client ID and secret)
2. Organization ID
3. Access token (obtained using your credentials)

Getting your credentials

1. Log in to your Apiera Dashboard.
2. Navigate to Settings > API Access.
3. Create a new API client.
4. Save your Client ID, Client Secret, and Organization ID.

Obtaining an access token

Request an access token from the Apiera authorization server using your client credentials:

POST /oauth/token HTTP/1.1
Host: auth.apiera.io
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.apiera.io",
  "grant_type": "client_credentials",
  "organization": "org_YOUR_ORG_ID"
}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Making authenticated requests

Include the access token in the Authorization header on every request:

GET /v1/products HTTP/1.1
Host: api.apiera.io
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Token expiration

Access tokens expire after 24 hours (expires_in: 86400 seconds). When a token expires, the API returns a 401 Unauthorized response. Request a new token using your client credentials and retry the failed request.

Caching tokens

The recommended approach is to cache the token using the expires_in value from the response as the TTL, with a small safety buffer to avoid using a token that is about to expire:

1. Request a token.
2. Cache the token with a TTL of expires_in - 60 seconds.
3. On subsequent requests, return the cached token.
4. When the cache expires, request a new token.

This ensures you make exactly one token request per expiry cycle, regardless of how many API calls you make.

C# example using in-memory cache:

public sealed class CachedTokenProvider
{
    private readonly SemaphoreSlim _semaphore = new(1, 1);
    private string? _cachedToken;
    private DateTimeOffset _expiresAt;

    public async Task<string> GetTokenAsync(CancellationToken cancellationToken = default)
    {
        if (_cachedToken is not null && DateTimeOffset.UtcNow < _expiresAt)
            return _cachedToken;

        await _semaphore.WaitAsync(cancellationToken);
        try
        {
            // Double-check after acquiring lock
            if (_cachedToken is not null && DateTimeOffset.UtcNow < _expiresAt)
                return _cachedToken;

            var response = await RequestTokenAsync(cancellationToken);
            _cachedToken = response.AccessToken;
            _expiresAt = DateTimeOffset.UtcNow.AddSeconds(response.ExpiresIn - 60);

            return _cachedToken;
        }
        finally
        {
            _semaphore.Release();
        }
    }
}

Key details:

• 60-second buffer prevents using a token right as it expires.
• Semaphore ensures concurrent requests don't trigger multiple token requests simultaneously.
• If you use a distributed cache (Redis, etc.), use the same TTL strategy so all instances of your application share a single cached token.

Best practices

Secure credentials. Store client secrets in environment variables or a secrets manager, never in source code.

Use separate credentials for development, staging, and production environments.

Common errors