Authorizing Turnqey
Use this flow when a client needs to connect an exchange account to Turnqey with read-only access.
Turnqey does not request trading, withdrawal, transfer, or private-key permissions.
Supported platforms
platform value | Source |
|---|---|
coinbase | Coinbase |
gemini | Gemini |
Any other value is rejected with "Platform is not supported yet".
Authorization endpoint
This is a browser redirect flow.
Your application sends the user to the Turnqey authorization URL with query parameters. The user completes the source-platform authorization flow, then Turnqey redirects back to the redirect URL registered for your client during onboarding.
| Environment | Browser redirect URL |
|---|---|
| Production | https://api.turnqey.xyz/authorize |
The sandbox mocks the data endpoints only and has no /authorize flow. Contact support@turnqey.xyz to arrange testing of account linking.
Method: GET. No bearer token: the checksum proves the link came from your backend.
Query parameters
| Parameter | Required | Description |
|---|---|---|
| client | Yes | Client ID provided by Turnqey. |
| platform | Yes | coinbase or gemini. |
| identity | Yes | Your user or client identifier. Returned on redirect, and later usable with GET /v1/api/account/identity/{identity}. |
| checksum | Yes | Value from GET /v1/api/checksum, generated for the same platform, collection, and identity. |
| collection | No | Existing collection UUID. Use it to group this connection with earlier ones. Omit it to create a new collection. |
| state | Recommended | Unguessable random string for CSRF protection. Returned unchanged on redirect. |
Step 1: generate the checksum
From your backend, call the checksum endpoint with your bearer token and the same values you will put on the authorization URL:
curl -X GET 'https://api.turnqey.xyz/v1/api/checksum?platform=coinbase&collection=COLLECTION_ID&identity=PARTNER_USER_ID' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": {
"checksum": "3f9c1b0a7d4e2f6c8b5a9d1e0c7f4b2a6e8d3c1f",
"expiresIn": 900
}
}The checksum is valid for expiresIn seconds, so generate it right before sending the user. If you omit collection here, omit it on the authorization URL too. If platform, collection, or identity differ between the two calls, the link is rejected as a tampered request. See Generate authorization checksum.
Step 2: send the user to the authorization URL
https://api.turnqey.xyz/authorize?client=CLIENT_ID&platform=coinbase&collection=COLLECTION_ID&state=RANDOM_STATE&identity=PARTNER_USER_ID&checksum=CHECKSUMURL-encode every value. The user signs in at the source platform and grants read-only access. The user should finish within 30 minutes of opening the link.
Step 3: handle the redirect back
On success, Turnqey redirects the browser to your registered redirect URL:
https://your-app.example.com/callback?success=true&account=ACCOUNT_ID&collection=COLLECTION_ID&state=RANDOM_STATE&identity=PARTNER_USER_ID| Parameter | Description |
|---|---|
| success | true |
| account | UUID of the newly linked account. Use it with the balances and transactions endpoints. |
| collection | UUID of the collection the account joined. Store it if Turnqey created a new one. |
| state | The value you sent. Reject the callback if it does not match. |
| identity | The value you sent. |
On failure, the user sees a Turnqey error page and is then sent to your redirect URL with:
https://your-app.example.com/callback?success=false&message=REASONmessage | Cause |
|---|---|
| Missing identity parameter in the request | identity was empty. |
| Tampered request | checksum did not match, or it expired. |
| Platform is not supported yet | platform missing or not coinbase / gemini. |
If the failure happens later, at the source platform, message carries a general error description. If client is missing, Turnqey cannot identify your redirect URL, so the user stays on the Turnqey error page.
Flow summary
- Your backend creates or retrieves the partner user identity.
- Your backend generates a
statevalue. - Your backend calls
GET /v1/api/checksumfor the sameplatform,collection, andidentity. - Your frontend redirects the user to the authorization URL.
- The user grants read-only access at the source platform.
- Turnqey redirects back with
success,account,collection,state, andidentity. - Your backend checks
state, then reads data with the account, collection, or identity endpoints.
Collections
Use collection when you want multiple accounts or sources grouped under one client household, estate, adviser record, or partner workflow.
If collection is omitted, Turnqey creates a new collection and returns its UUID on redirect.
Reconnects
Some source platforms can revoke or expire authorization. When that happens, the data endpoints keep serving the last snapshot and flag it: dataFreshness.status and transactionSyncStatus become reconnect_required. See Data Freshness.
Show the client a clear reconnect action that runs this flow again, instead of retrying forever.
Support
For integration support, contact: