POST /oauth/token
Exchange your integration credentials (client_id + client_secret) for a short-lived Bearer token. This is the recommended authentication method for all programmatic integrations.
This endpoint does not require prior authentication. Credentials are provisioned by your DokStamp account manager.
Request
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
| Parameter | Type | Required | Description |
|---|
grant_type | string | Yes | Must be client_credentials |
client_id | string | Yes | Your integration client ID |
client_secret | string | Yes | Your integration client secret |
curl -X POST https://api.dokstamp.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
Response 200
{
"token_type": "Bearer",
"expires_in": 43200,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}
| Field | Type | Description |
|---|
access_token | string | Bearer token — include in Authorization header of all API requests |
expires_in | integer | Validity in seconds (43200 = 12 hours) |
token_type | string | Always "Bearer" |
Error 401
{
"error": "invalid_client",
"error_description": "Client authentication failed",
"message": "Client authentication failed"
}
Using the token
Add the token to every subsequent request:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Accept: application/json
X-Tenant: your-tenant-identifier
Token expiry and renewal
Service tokens expire after 12 hours. There is no refresh token — request a new token when the current one expires. Recommended pattern: cache the token and renew it proactively ~60 seconds before expiry.
let token = null;
let expiresAt = null;
async function getToken() {
if (token && Date.now() < expiresAt - 60_000) return token;
const res = await fetch('https://api.dokstamp.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.DOKSTAMP_CLIENT_ID,
client_secret: process.env.DOKSTAMP_CLIENT_SECRET,
}),
});
const data = await res.json();
token = data.access_token;
expiresAt = Date.now() + data.expires_in * 1000;
return token;
}
Rotating credentials
If a client_secret is compromised, contact your DokStamp account manager to rotate the credentials. A new client_id / client_secret pair will be issued and all existing tokens for the old credentials will be immediately revoked.
