Authentication

Compliancely APIs uses JWT (JSON Web Token) authentication.

To keep your data secure and ensure only authorized clients can access our services, all API requests require authentication via JSON Web Tokens (JWT). Our authentication system uses a two-token approach — an access token for making requests and a refresh token for obtaining new access tokens without re-entering credentials.

The process is straightforward:

• Sign in once with your username and password to get your access and refresh tokens.
• Use your access token in every API request until it expires.
• Refresh it seamlessly with your refresh token when needed.
• Validate tokens anytime to check their status and remaining lifetime.

This approach ensures:

• Fewer authentication calls, reducing API load and improving performance.
• Secure token storage for quick re-authentication.
• A consistent, reliable method for all clients, whether you're building asynchronous jobs, UI integrations, or backend services.

Implement token caching in your application to avoid unnecessary calls and keep things lightning-fast.

For full endpoint details, see:

/api/v2/token/ – Initial authentication.

/api/v2/token/refresh/ – Get a new access token.

/api/v2/token/validate/– Verify token validity.

❗️

Note: We do not recommend using of Basic Auth.

Basic Authentication and API V1 are scheduled for deprecation on May 31, 2026. Clients should migrate before this date.

Validity

The access_token is valid for 1 hour. After it expires, you can use the Access Token by Refresh Token endpoint to obtain a new access_token.
The refresh_token remains valid for 24 hours.

Throttling

This API enforces throttling, allowing a maximum of 10 requests per minute (RPM). If you exceed this limit, the following error will be returned, and you will need to wait 10 minutes before retrying.

{  
    "detail": "Your request has been throttled due to exceeding the allowed rate limit. Please wait for 10 minutes before trying again. If this issue persists, consider adjusting the request frequency or contact support for further assistance."  
}

Response codes and errors

V2 Authentication – Recommended Workflow

V2 uses a short‑lived access token (1 hour) and a long‑lived refresh token (24 hours). The goal is seamless rotation before expiry—no waiting for tokens to expire. Below is the complete recommended flow.

Initial Login / Token Creation

Endpoint: /api/v2/token/create Purpose: Retrieve your first token pair. You receive:

access_token (valid 1 hour) refresh_token (valid 24 hours)

When to call it:

• Only once per day (or once per environment startup
• Not required for each request

Access Token Validation (Optional but Recommended)

Endpoint: /api/v2/token/validate Purpose: To quickly check if your current access token is still valid.

Recommended use cases:

• Before making large batches of API calls
• During scheduled jobs
• Debugging or monitoring token health

Not required on every request because validation adds overhead. Client applications typically store token timestamps and proactively refresh.

Proactive Token Refresh (Highly Recommended)

Endpoint: /api/v2/token/refresh Purpose: Generate a new access token

When should you call it?

• You do NOT need to wait for expiration.
• You can refresh any time before expiry.
• Best practice refresh timing:

Access token: Refresh ~10–15 minutes before the 1‑hour mark Refresh token: Refresh every 12 hours (or earlier depending on your job schedule)

The refresh response returns:

new_access_token (1 hour validity) new_refresh_token (24 hour validity)

You simply replace both tokens in your application. No downtime. No expired windows.

What happens if tokens expire?

If access token expires, use the refresh token to get a new pair. If both expire, call /token/create again.

This is typically rare if proactive refresh is used.

Handling Failures

If an API request fails due to an authentication or token refresh error other than invalid credentials, clients should attempt automated recovery using the following steps:

1. Attempt a token refresh once
   1. If the access token is expired, initiate the standard refresh token flow.
   2. Do not retry the same request indefinitely.
2. If token refresh fails with a 4XX error, other than 401
   1. Discard both access and refresh tokens.
   2. Obtain a new token set using the original authentication flow.
3. Do not automatically retry errors caused by invalid credentials.
4. If re-authentication fails, surface the error and stop retrying.

For any assistance, reach out to [email protected]