Turnqey API Authentication Guide

Welcome to Turnqey's API authentication guide. This document will walk you through the process of authenticating with our API service to access Turnqey's crypto asset data aggregation platform. As a developer integrating with our APIs, understanding our authentication model is the first step to building powerful 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.

Before you begin, you should have:

1. A Turnqey account with API access enabled
2. Your client ID and client secret (provided during onboarding)
3. Registered your IP addresses with Turnqey for API access

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.

The authentication process follows these steps:

1. Request an access token using your client ID and client secret
2. Receive a JWT token that's valid for one hour
3. Include this token in the Authorization header of all subsequent API requests
4. Request a new token when the current one expires

To request an access token, make a POST request to our token endpoint with your client credentials.

POST https://api.turnqey.xyz/v1/api/token

POST https://sandbox.turnqey.xyz/v1/api/token

curl -X GET 'https://api.turnqey.xyz/v1/api/token' \
  -H 'accept: application/json' \
  -H 'clientId: your_client_id' \
  -H 'clientSecret: your_client_secret'

{
  "statusCode": 200,
  "message": "POST Request successful.",
  "isError": false,
  "result": {
    "expiresOn": "2024-06-14T13:29:36.8287785+05:30",
    "expiresIn": 3599,
    "token": "eyJ0eXAiO.............................................WLLC26yzxcDiuqJjg"
  }
}

The accessToken is a JSON Web Token (JWT) that expires in one hour (3600 seconds).

{
    "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": {
                "ClientId": [
                    "The ClientId field is required."
                ],
                "ClientSecret": [
                    "The ClientSecret field is required."
                ]
            },
            "traceId": "00-0bc42ada3bcc75768a1s3eac5cf3f939-2c4a967c49b4aa1d-00"
        }
    }
}

Access tokens expire after one hour (3600 seconds). Your application should handle token expiration gracefully by:

1. Tracking token expiration time (based on the expiresIn value)
2. Proactively refreshing tokens before they expire
3. Handling 401 Unauthorized responses by obtaining a new token and retrying the request

1. Check the token expiration time and ensure you're refreshing before it expires
2. Verify you're using the correct endpoint for your environment (production vs. sandbox)
3. Ensure the Authorization header is properly formatted: Authorization: Bearer your_token_here

• Regular security assessments and penetration testing
• Last Penetration Testing: June 3, 2025

• SOC 2 Type II certification in process, expected completion Q2 2026
• All security controls designed to meet SOC 2 Trust Services Criteria