This page shows how to build x-client-authorization envelope once and reuse it.
| 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. |
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.
"Bearer " prefix prepended before encryption.sub + iss + dest.