Authentication

Securely authenticate your applications using Admin's OAuth 2.0, API keys, and JWT token flow.

Overview

Admin supports multiple authentication methods depending on your use case. The recommended approach for most applications is the JWT Bearer Token flow, which provides stateless, secure authentication with automatic token rotation.

Supported Methods

JWT Authentication Flow

The JWT flow consists of three steps: obtaining an access token, making authenticated requests, and refreshing tokens before expiration.

Step 1: Obtain Access Token

Send your client credentials to receive a short-lived access token and a refresh token.

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Step 2: Make Authenticated Requests

Include the access token in the Authorization header of your API requests:

curl -X GET https://api.admin.io/v3/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Error Handling

Authentication errors return standard HTTP status codes with structured JSON responses:

{
  "error": "invalid_token",
  "message": "The access token provided has expired or is malformed.",
  "code": "AUTH_TOKEN_EXPIRED",
  "details": {
    "issued_at": "2025-03-15T10:00:00Z",
    "expired_at": "2025-03-15T11:00:00Z"
  }
}

Security Best Practices

• Always use HTTPS for token exchange and API requests
• Store tokens in secure, HTTP-only cookies or memory-only stores
• Implement token rotation and revocation strategies
• Use short-lived access tokens (≤ 1 hour) and long-lived refresh tokens
• Validate tokens on the server side using Admin's public JWKS endpoint