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:

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.

Authentication Flow Overview

The authentication process follows these steps:

1. Request an access token using your client ID and client secret
2. Receive a JWT token that is 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

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/token

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

Request body

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": "Success",
  "isError": false,
  "result": {
    "expiresIn": 3600,
    "token": "eyJ0eXAiO.............................................WLLC26yzxcDiuqJjg"
  }
}

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

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": {
                "ClientId": [
                    "The ClientId field is required."
                ],
                "ClientSecret": [
                    "The ClientSecret field is required."
                ]
            }
        }
    }
}

Token Lifecycle Management

Token Expiration

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

Troubleshooting

Debugging Tips

1. Check the token expiration time and ensure you are refreshing before it expires
2. Verify you are using the correct endpoint for your environment (production vs. sandbox)
3. 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.