Exchange Authentication Token
The POST /api/auth/x-token endpoint exchanges a valid existing Bearer token for a newly issued one. This allows integrations to maintain continuous, secure session access without forcing the user or service to re-enter credentials. If the provided token is invalid or expired, the request will fail with an appropriate error response.
Endpoint
POST /api/auth/x-token
Authentication
Bearer token required. Obtain via:
POST https://api.banking.netevia.dev/api/auth/v2Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.
When to use
Use this endpoint when your integration needs to proactively rotate an active token before it expires, extending the session without interruption. This is particularly useful in long-running workflows or background services where prompting for credentials is not feasible. It is distinct from the standard refresh flow (/api/auth/refresh) in that it performs a full token exchange rather than a lightweight renewal.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| clientId | string | No | Optional client identifier used to associate the token exchange with a specific client context. |
Response
200 OK
The response body is a plain string containing the newly issued Bearer token.
| Field | Type | Description |
|---|---|---|
| (body) | string | The new Bearer token to use for subsequent authenticated requests. |
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMTIzIiwicGFydG5lcklkIjoicDAwMSIsImV4cCI6MTcwMDAwMDYwMH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"Error Codes
| Code | When it happens |
|---|---|
| 400 | Missing required fields or validation error |
| 401 | Token missing, expired, or invalid — the existing token could not be validated |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 500 | Internal server error |
Common Mistakes
- Sending an already-expired token — this endpoint requires a currently valid token to perform the exchange; use
/api/auth/v2to obtain a fresh token if the current one has expired. - Omitting the
Authorization: Bearerheader entirely — the existing token must be passed in the header, not the request body. - Confusing this endpoint with
/api/auth/refresh— use/api/auth/x-tokenwhen a full token exchange is needed; use/api/auth/refreshfor a standard lightweight token renewal.
Related Endpoints
POST /api/auth/v2— Obtain an initial Bearer token using username, password, and partnerIdPOST /api/auth/refresh— Refresh an existing token using the standard renewal flow
Example
curl -X POST https://api.banking.netevia.dev/api/auth/x-token \
-H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
-H "Content-Type: application/json"With optional clientId query parameter:
curl -X POST "https://api.banking.netevia.dev/api/auth/x-token?clientId=your-client-id" \
-H "Authorization: Bearer YOUR_EXISTING_TOKEN" \
-H "Content-Type: application/json"