Generate JWT access token
POST /api/auth/token
POST https://<api-host>/api/auth/tokenAuthenticate with the X.509 client certificate + credentials (clientId/clientSecret) and receive a JWT token. The token lifetime comes in the expires_in field (in seconds): use that value to renew the token before it expires, instead of assuming a fixed duration.
Authentication (mTLS)
This route requires mTLS: the client certificate issued by Gateways is presented in the TLS handshake, not in an HTTP header. Use the native client certificate mechanism of your HTTP library (for example, curl --cert client.crt --key client.key).
- The certificate is PEM, RSA 2048, valid for 2 years and bound to your account.
- mTLS is required only on this route. All other routes use
Authorization: Bearer <token>, without a certificate.
Do not send the certificate in HTTP headers: that model is not accepted. Without the certificate in the handshake, the API responds 400 with PUB_CERT_HEADER_MISSING.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
clientId | string (UUID v4) | Yes | Client ID generated in the dashboard (https://<dashboard-host>), under Settings → Credentials |
clientSecret | string | Yes | Client secret generated together with the clientId. It is shown only once in the dashboard. Must not be empty |
{
"clientId": "6967c0a0-3566-48d0-8c13-717038b52279",
"clientSecret": "YOUR_CLIENT_SECRET"
}cURL Example
curl -X POST https://<api-host>/api/auth/token \
--cert ./client.crt \
--key ./client.key \
-H "Content-Type: application/json" \
-d '{
"clientId": "YOUR_CLIENT_ID",
"clientSecret": "YOUR_CLIENT_SECRET"
}'Code Examples
const https = require('https');
const fs = require('fs');
const axios = require('axios');
const httpsAgent = new https.Agent({
cert: fs.readFileSync('./client.crt'),
key: fs.readFileSync('./client.key'),
});
const response = await axios.post(
'https://<api-host>/api/auth/token',
{
clientId: process.env.PIX_API_CLIENT_ID,
clientSecret: process.env.PIX_API_CLIENT_SECRET,
},
{ httpsAgent },
);
console.log('Token:', response.data.access_token);
console.log('Expires in:', response.data.expires_in, 'seconds');Gateways delivers the certificate as PEM (client.crt + client.key). If your platform requires a .pfx/.p12 file (common in Java and some Windows/.NET environments), convert it locally:
openssl pkcs12 -export -in client.crt -inkey client.key -out client.p12The conversion happens on your machine; Gateways does not provide PFX files.
Response (201)
| Field | Type | Description |
|---|---|---|
access_token | string | JWT token for the Authorization: Bearer <token> header |
token_type | string | Always Bearer |
expires_in | number | Token lifetime in seconds. Renew before it expires based on this value |
scope | string | Token scope |
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "email profile"
}Errors
| Status | Code | Description |
|---|---|---|
| 400 | PUB_CERT_HEADER_MISSING | Client certificate not presented in the TLS handshake |
| 400 | PUB_CERT_MALFORMED_PEM | Certificate in invalid PEM format |
| 400 | PUB_REQUEST_BODY_INVALID | Invalid body (e.g. clientId is not a UUID v4, empty clientSecret, extra fields). The offending fields are listed in details.violations |
| 401 | PUB_INVALID_CREDENTIALS | Invalid clientId/clientSecret |
| 401 | PUB_CERT_NOT_VERIFIED | The certificate could not be verified on the connection |
| 401 | PUB_CERT_NOT_REGISTERED | Certificate not registered |
| 401 | PUB_CERT_EXPIRED | Certificate expired |
| 401 | PUB_CERT_NOT_YET_VALID | Certificate is not yet within its validity period |
| 403 | PUB_CERT_NOT_AUTHORIZED_FOR_ACCOUNT | Certificate is not bound to the account of the credentials |
| 502 | PUB_AUTH_UPSTREAM_ERROR | Unexpected error in the authentication service |
| 503 | PUB_AUTH_UPSTREAM_UNAVAILABLE | Authentication service temporarily unavailable. Try again |
{
"statusCode": 401,
"timestamp": "2026-04-17T15:24:28.809Z",
"path": "/api/auth/token",
"method": "POST",
"code": "PUB_INVALID_CREDENTIALS",
"message": "Invalid credentials provided",
"userMessage": "Invalid credentials.",
"errorId": "75d7999d6d7656b737e83435ced86ec6"
}For a complete authentication guide with token renewal patterns, see Authentication Guide.