API authentication guide

To work with the BTC Direct API, you must first obtain a JWT (JSON Web Token) by authenticating with the /api/v1/authenticate endpoint. The token is required for all subsequent API requests.

Requesting a JWT token

Send a POST request to POST /api/v1/authenticate with your partner credentials:

curl -X POST https://api-sandbox.btcdirect.eu/api/v1/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}'

Response:

{
  "token": "eyJ...",
  "refreshToken": "abc123..."
}

Include the token in all subsequent requests:

Authorization: Bearer {token}

Token expiry

Tokens are valid for 1 hour. When a token expires, the API returns a 400 Bad Request error:

{
  "errors": {
    "ER801": {
      "code": "ER801",
      "message": "Authorization token has expired.",
      "solution": "Request a new authorization token."
    }
  }
}

Refreshing the token

To get a new token without re-authenticating, send a POST request to POST /api/v1/refresh with your refresh token:

curl -X POST https://api-sandbox.btcdirect.eu/api/v1/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "YOUR_REFRESH_TOKEN"}'

Response:

{
  "token": "eyJ...",
  "refreshToken": "def456..."
}

The refresh token is valid for 1 month but resets when a new token is generated.