Turnqey API Authentication Guide
Introduction
Welcome to Turnqey's API authentication guide. This document walks you through authenticating with our API service to access Turnqey's cryptoasset data aggregation platform. As a developer integrating with our APIs, understanding our authentication model is the first step to building crypto portfolio tracking applications.
Turnqey uses a standard OAuth 2.0 Client Credentials flow for API authentication. This guide explains how to request access tokens, use them correctly, and implement best practices for token management in your applications.
Prerequisites
Before you begin, you should have:
- A Turnqey account with API access enabled
- Your client ID and client secret (provided during onboarding)
- If your agreement requires it, your server IP addresses registered with Turnqey (Turnqey tells you during onboarding)
Security Notice: Your client ID and client secret are sensitive credentials. Never share these values in client-side code, public repositories, or with unauthorized parties.
Authentication Flow Overview
The authentication process follows these steps:
- Request an access token using your client ID and client secret
- Receive a JWT token together with its lifetime (
expiresIn, in seconds) and expiry time (expiresOn) - Include this token in the Authorization header of all subsequent API requests
- Request a new token shortly before the current one expires
Requesting an Access Token
To request an access token, make a POST request to the token endpoint with your client credentials in the JSON request body.
Endpoints
POST https://api.turnqey.xyz/v1/api/tokenPOST https://tq-sandbox-api.azurewebsites.net/api/v1/byallaccounts/tokenThe sandbox is a mock of this API with a different path prefix (/api/v1/byallaccounts/... instead of /v1/api/...). It also needs a sandbox API key: create one in the sandbox portal and send it as Authorization: Bearer YOUR_SANDBOX_API_KEY (or the x-api-key header) on every sandbox request, including the token request. The sandbox has no /authorize flow.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| clientId | string | Yes | The client ID provided by Turnqey. |
| clientSecret | string | Yes | The client secret provided by Turnqey. |
Send accept: application/json and content-type: application/json headers with the request.
curl -X POST 'https://api.turnqey.xyz/v1/api/token' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
"clientId": "your_client_id",
"clientSecret": "your_client_secret"
}'{
"statusCode": 200,
"message": "POST Request successful.",
"isError": false,
"result": {
"expiresOn": "2026-10-30T17:10:43+00:00",
"expiresIn": 3599,
"token": "eyJ0eXAiO.............................................WLLC26yzxcDiuqJjg"
}
}| Field | Description |
|---|---|
token | JSON Web Token (JWT) to send as Authorization: Bearer {token}. |
expiresIn | Seconds until the token expires. |
expiresOn | Absolute expiry time. |
The lifetime is set by the identity provider and is not a fixed value. Always read it from the response instead of assuming one hour.
Common Error Responses
{
"statusCode": 400,
"isError": true,
"responseException": {
"exceptionMessage": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"$": [
"JSON deserialization for type 'Turnqey.Data.DTOs.Requests.TokenRequest' was missing required properties, including the following: clientId, clientSecret"
],
"tokenRequest": [
"The tokenRequest field is required."
]
},
"traceId": "00-e824a265fff8350861dc4cbef24164f3-dc9f5895f7a7759e-00"
}
}
}| Status | Meaning |
|---|---|
| 400 | Request body malformed, or clientId / clientSecret missing. |
| 401 | Client credentials rejected. |
| 429 | Too many token requests from your IP. See Rate limits below. |
Rate limits
Limits are counted per source IP address.
| Endpoint | Limit |
|---|---|
POST /v1/api/token | 30 requests per minute (an additional limiter caps bursts at 60 per minute) |
Account endpoints (/v1/api/account/...) | 300 requests per minute, counted separately for each endpoint path |
When a limit is exceeded the API returns 429 Too Many Requests with these headers:
| Header | Meaning |
|---|---|
Retry-After | Seconds to wait before retrying. |
X-RateLimit-Limit | Requests allowed in the current window. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Unix time when the window resets. |
Reuse one token until it nears expiry. Requesting a new token for every API call will hit the token limit quickly.
Token Lifecycle Management
Token Expiration
Access tokens expire at the time given by expiresOn (or expiresIn seconds after issue). Your application should handle token expiration gracefully by:
- Tracking token expiration time (based on the
expiresOnorexpiresInvalue) - Proactively refreshing tokens before they expire
- Handling 401 Unauthorized responses by obtaining a new token and retrying the request
Troubleshooting
Debugging Tips
- Check the token expiration time and ensure you are refreshing before it expires
- Verify you are using the correct endpoint for your environment (production vs. sandbox)
- Ensure the Authorization header is properly formatted:
Authorization: Bearer your_token_here
Security and Compliance
Turnqey operates read-only and follows established security practices, including regular third-party security assessments and penetration testing. Security controls are designed against the SOC 2 Trust Services Criteria.
For the current security posture and compliance details, see Security and Compliance.