Authentication

All API requests are authenticated using a Service Token — a short-lived Bearer token obtained via the OAuth2 Client Credentials grant. This is a machine-to-machine flow: no human login is involved.

How it works

Your integration holds a client_id and client_secret (provided by your DokStamp account manager). Exchange them for an access token, then include that token in every API request.

client_id + client_secret
        │
        ▼
POST /oauth/token
        │
        ▼
access_token (valid 12h)
        │
        ▼
Authorization: Bearer {access_token}

1. Obtain a token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

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"

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 { access_token, expires_in } = await res.json();

$response = Http::asForm()->post('https://api.dokstamp.com/oauth/token', [
    'grant_type'    => 'client_credentials',
    'client_id'     => env('DOKSTAMP_CLIENT_ID'),
    'client_secret' => env('DOKSTAMP_CLIENT_SECRET'),
]);
$token = $response->json('access_token');

Response:

{
  "token_type": "Bearer",
  "expires_in": 43200,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

Field	Description
`access_token`	Include in every API request via `Authorization: Bearer`
`expires_in`	Validity in seconds — 43 200 = 12 hours

2. Use the token

Include the token in every subsequent request:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Accept: application/json
X-Tenant: your-tenant-identifier

3. Token renewal

Tokens expire after 12 hours. There is no refresh token — request a new one with your credentials when needed. Recommended pattern: cache the token and renew 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;
}

Public endpoints

These endpoints do not require authentication:

Endpoint	Purpose
`POST /oauth/token`	Obtain a service token
`GET /files/{uuid}/download`	Download a signed document

Store client_id and client_secret in environment variables or a secrets manager. Never commit them to source code.

Getting Started

Core Concepts

Authentication

Institutions

Organizations

Courses

Modules

Students

Enrollments

Certificates

Certificate Templates

Files

Guides

Integration Guide

Authentication

Authentication

How it works

1. Obtain a token

2. Use the token

3. Token renewal

Public endpoints

​Authentication

​How it works

​1. Obtain a token

​2. Use the token

​3. Token renewal

​Public endpoints

Authentication

How it works

1. Obtain a token

2. Use the token

3. Token renewal

Public endpoints