x-client-authorization is a signed, encrypted token you generate once and send on async document operations (POST /documents/document/generate/async, POST /documents/document/merge/async). It doesn't authenticate the async request itself, that's Authorization. It authenticates the callback Doctavian sends back to your service once the async result is ready.
| Claim | Description |
|---|---|
sub | Required. The access token used to authenticate to your callback endpoint when Doctavian delivers the async result |
iss | Required. The base URL of the service that will receive the callback. Combined with dest, forms the full callback URL: iss + dest |
dest | Required. The route of the callback endpoint on your service, e.g. /temp/callback. Not a full URL on its own — see iss above |
oid | An identifier for the callback service itself, e.g. user ID |
client_id | An identifier for the client making the call, e.g. org ID |
full_name | Caller's name |
email | Caller's email address |
locale | Caller's locale. |
zoneinfo | Caller's timezone. |
issanddestcan't point back to Doctavian's own API. Together they form the callback URL Doctavian calls once your async request completes — if that URL falls within Doctavian's own API, the token is rejected to prevent a callback loop.
Send your claims as plain JSON to POST /common/client/token. Doctavian validates, signs, and encrypts the payload, and returns the finished value ready to drop straight into the x-client-authorization header.
POST https://api.doctavian.com/v1/common/client/token
Authorization: Bearer <token>
x-api-key: <api-key>
Content-Type: application/json
{
"sub": "<access token for your callback endpoint>",
"dest": "/temp/callback",
"full_name": "Jane Smith",
"email": "jane.smith@example.com",
"iss": "https://your-system.example.com",
"oid": "<id of the callback service, e.g. user id>",
"client_id": "<id of the client, e.g. org id>",
"zoneinfo": "Europe/Dublin",
"locale": "en"
}A successful call returns the signed and encrypted token as a string:
{
"result": {
"data": {
"token": "<signed and encrypted x-client-authorization value>"
},
"statusCode": 200,
"message": "OK"
}
}Use result.data.token as-is for the x-client-authorization header on your async request. In this example, Doctavian would deliver the callback to https://your-system.example.com/temp/callback, authenticating with the token in sub.
You don't need to set
iatorexpyourself — the endpoint handles token timing as part of signing.
| Symptom | Cause | Returned |
|---|---|---|
| Wrong AES key/IV, tampering, or bad base64 | Decryption fails | 400 X_CLIENT_AUTH_ERROR ("Invalid format") |
| Unsigned or wrongly-signed JWT, or expired | Signature/expiry check fails | 401 |
| A required claim is missing | Claim check fails | 400 ("missing claims") |
| Async operation sent without the client header | Presence guard fails | 400 X_CLIENT_AUTH_ERROR ("header is missing for async operations") |
See Troubleshooting for the full table across all headers.
sub, iss, and dest — all three are required.dest is a route only (e.g. /temp/callback), not a full URL — iss and dest together form the full callback URL.iss and dest don't resolve to Doctavian's own API.oid, client_id, full_name, email, locale, zoneinfo) are only included if your callback actually needs them — it's fine to omit them.iat and exp are left out — the token endpoint sets these for you.