Authentication

Every API request carries an access token in the Authorization header. You get the token by exchanging an API key, a Client ID and a Client secret, at the token endpoint.

Create an API key

API keys are created in the DocPayload app under Dashboard > Settings > API access > Manage keys > Generate Key.

A key is a pair:

Part	Example	Notes
Client ID	b0aa7303e6704e2188b42681d7b353fe	32 hexadecimal characters
Client secret	a long random string	Shown once, when the key is generated. Copy it then: it won't be shown again

A key expires after about six months; the dialog shows its expiry date. The same dialog shows your Tenant ID, which every endpoint takes in its path.

Exchange the key for an access token

Send the Client ID and secret to the token endpoint:

curl -X POST https://api.docpayload.com/v1/api-auth/token \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET" }'

Success (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "document:read document:write metrics:read asset:upload document:delete"
}

Wrong credentials are answered 401 Unauthorized.

Use the access token

Every other call, downloading a generated document included, sends the token as a Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

The token lasts 3600 seconds (expires_in). Keep it and reuse it for every call until it expires, then request a new one; do not request a token per call.

IP allow-list

The API access dialog also holds an optional IP allow-list. When it is set, only the listed addresses may use your keys.

Security best practices

• Store the Client ID and secret in environment variables or a secret store, never in source code
• Rotate a key by generating a new one, moving your integration to it, then revoking the old one
• Set the IP allow-list to the addresses your servers call from
• Keep the access token on the server; never send the secret or the token to a browser

Error responses

Status	Description
401 Unauthorized	Missing, invalid or expired access token, or wrong Client ID or secret
403 Forbidden	The token has no permission for this resource, or the URL names another tenant
429 Too Many Requests	Rate limit exceeded