Authentication

All GoDark API endpoints use a single authentication model: long-lived api_key + api_secret + passphrase credentials are exchanged for a short-lived bearer token via OAuth 2.0 client_credentials.

Credential Model

Layer	Credential	Lifetime	Purpose
Long-lived	`api_key` + `api_secret` + `passphrase`	Until rotated	Identify your account. The `passphrase` is set by you at key-creation time and must be supplied with every token exchange — it is not recoverable if lost.
Short-lived	`access_token` (JWT Bearer)	15 minutes	Sent with every REST request and on WebSocket `login`.

Generate and manage api_key / api_secret / passphrase triples from the app under Settings → API Keys. The passphrase is shown once at creation time; if you lose it, rotate the key.

POST /auth/token

Exchange credentials for a bearer token. RFC 6749 client_credentials grant.

POST /api/v1/auth/token

Request

Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "<api_key>",
  "client_secret": "<api_secret>",
  "passphrase": "<passphrase>"
}

Response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "trade read"
}

Field	Description
`access_token`	Short-lived JWT bearer token.
`token_type`	Always `Bearer`.
`expires_in`	Token lifetime in seconds (default `900` = 15 min).
`scope`	Space-separated list of granted scopes (`trade`, `read`).

cURL

curl -X POST https://api.godarkdex.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_API_KEY",
    "client_secret": "YOUR_API_SECRET",
    "passphrase": "YOUR_PASSPHRASE"
  }'

POST /auth/token/revoke

Invalidate an access token before its natural expiry. RFC 7009.

POST /api/v1/auth/token/revoke

Request

{
  "token": "eyJhbGciOi..."
}

Response

204 No Content on success. Revoking an already-expired or unknown token is a no-op and also returns 204.

Using the Bearer Token

Every subsequent REST request must include:

Authorization: Bearer <access_token>

For WebSocket, authenticate the socket with an op: "login" frame carrying the same token — see WebSocket Trading.

Token Expiry

Access tokens expire after 15 minutes. On expiry:

REST: the next request returns 401 token_expired. Call POST /auth/token again.
WebSocket: the server emits an auth_expired event ~60 seconds before expiry. Send a fresh op: "login" with a new token to continue on the same socket without dropping subscriptions.

Public (Unauthenticated) Endpoints

The following endpoints do not require a bearer token:

POST /auth/token, POST /auth/token/revoke
GET /instruments, GET /instruments/{symbol}
GET /vip/tiers
GET /transparency

All other endpoints require Authorization: Bearer <token>.

Errors

Status	Code	Meaning
`400`	`invalid_request`	Malformed request (missing `grant_type`, `passphrase`, bad JSON).
`400`	`unsupported_grant_type`	Only `client_credentials` is supported.
`401`	`invalid_client`	Unknown `client_id`, bad `client_secret`, or bad `passphrase`.
`401`	`token_expired`	Bearer token is past its `expires_in` window.
`401`	`token_revoked`	Token was revoked via `/auth/token/revoke`.
`403`	`insufficient_scope`	Token lacks the required scope for the endpoint.

See Error Codes for the full reference.