Generate an API Bearer Token via Client Credentials

Exchange your client_id and client_secret for a short-lived bearer JWT. Tokens expire after 1 hour and must be refreshed server-side.

Call this endpoint to authenticate your server with the Shogun Integration API. You POST your client_id and client_secret, and the API returns a signed bearer JWT that you attach to every subsequent request. Tokens are short-lived — cache the token in memory server-side and proactively refresh it before it expires rather than waiting for a 401 response.

Endpoint

POST https://api.shogun.io/api/v1/security/api/generate_token

No Authorization header is required for this endpoint. Authentication is performed via the request body credentials.

Request body

client_id · string · required

Your public API client identifier. Find this in Dashboard → Security → API Client. Safe to log, but keep it paired with your client_secret.

client_secret · string · required

Your secret API key. Treat this like a password — never expose it in client-side code, logs, or source control. Rotate it immediately from the dashboard if it is ever compromised.

Request example

curl -X POST https://api.shogun.io/api/v1/security/api/generate_token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

Responses

200 — Authentication successful

The response envelope wraps a data object containing the bearer token and its metadata.

{
  "status": true,
  "message": "Authentication successful",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "client_id": "your-client-id",
    "authorities": [
      "TRANSACTION_READ"
    ]
  }
}

401 — Invalid credentials

Returned when the client_id or client_secret does not match a valid API client.

{
  "status": false,
  "message": "Invalid credentials"
}

429 — Rate limited / account locked

Returned after too many consecutive failed authentication attempts. The account is temporarily locked to prevent brute-force attacks.

{
  "status": false,
  "message": "Temporarily locked due to too many failed attempts."
}

Implement exponential backoff in your retry logic. Do not retry immediately on a 429 — wait before reattempting.

Never expose your client_secret in client-side code, mobile apps, browser JavaScript, or version control. All token generation must happen server-side. If your secret is compromised, rotate it immediately from Dashboard → Security → API Client — the old secret is invalidated instantly.

Token caching

Cache the returned access_token in your server’s memory or a secure store. Use expires_in (in seconds) to calculate the expiry time and schedule a refresh before the token lapses. Generating a new token on every request is unnecessary and will eventually trigger rate limiting.