Token Endpoint

Exchange an authorization code for an access token (and optionally an ID token if openid scope was requested). When the phone scope is granted, the ID token and userinfo response include phone_number and phone_number_verified. This must be done server-side — never expose your client secret in client-side code.

curl -X POST https://dhmad.tn/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://example.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code_verifier": "YOUR_CODE_VERIFIER"
  }'

const response = await fetch('https://dhmad.tn/api/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: 'AUTHORIZATION_CODE',
    redirect_uri: 'https://example.com/callback',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    code_verifier: 'YOUR_CODE_VERIFIER'
  })
});

const tokens = await response.json();

import requests

response = requests.post(
    'https://dhmad.tn/api/oauth/token',
    json={
        'grant_type': 'authorization_code',
        'code': 'AUTHORIZATION_CODE',
        'redirect_uri': 'https://example.com/callback',
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
        'code_verifier': 'YOUR_CODE_VERIFIER'
    }
)

tokens = response.json()

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email phone",
  "id_token": "eyJhbGciOiJIUzI1NiIs..."
}

Request Body

string

required

Must be authorization_code

string

required

The authorization code received from the authorize endpoint callback

string

required

Must exactly match the redirect_uri used in the authorization request

string

required

Your OAuth client ID

string

required

Your OAuth client secret

string

PKCE code verifier (required if code_challenge was provided during authorization)

Response Fields

ID Token Claims

When openid scope is included, the ID token contains:

Claim	Description
`iss`	Issuer (e.g., `https://dhmad.tn`)
`sub`	User ID
`aud`	Your client ID
`exp`	Expiration timestamp
`iat`	Issued-at timestamp
`email`	User’s email address
`email_verified`	Whether the email is verified
`name`	Full name
`given_name`	First name
`family_name`	Last name
`kyc_verified`	Whether the user has approved KYC on DHMAD
`kyc_status`	KYC status: `"pending"`, `"approved"`, `"rejected"`, or `null`

Error Responses

Unsupported grant type:

{
  "error": "unsupported_grant_type",
  "error_description": "Only 'authorization_code' grant type is supported"
}

Invalid or expired code:

{
  "error": "invalid_grant",
  "error_description": "Invalid or expired authorization code"
}

Invalid client credentials:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Redirect URI mismatch:

{
  "error": "invalid_grant",
  "error_description": "Invalid redirect_uri. Must exactly match the URI used during authorization."
}

Invalid PKCE verifier:

{
  "error": "invalid_grant",
  "error_description": "Invalid code_verifier"
}

Authorization codes expire after 10 minutes and can only be used once. Exchange the code immediately after receiving it.

Get Started

API Reference

Guides

Developer Portal

Request Body

Response Fields

ID Token Claims

Error Responses

​Request Body

​Response Fields

​ID Token Claims

​Error Responses

Request Body

Response Fields

ID Token Claims

Error Responses