The Valpay APIs use two credentials: a JSON Web Token (JWT) passed as a Bearer token, and an API key passed in the X-API-KEY header. Which credentials a request needs depends on the service.

Requirements by service

Request headers

Include the token on every request in the Authorization header, prefixed with Bearer, and the API key in the X-API-KEY header where required:

curl "https://api.valpay.com/v1/stores?limit=10&page=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/stores?limit=10&page=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/stores?limit=10&page=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Token format

Unauthorized responses

Requests with missing, malformed, or expired credentials are rejected with HTTP 401. Some endpoints also return 401 when the credentials are valid but lack the required permissions for the operation, or 403 when the operation requires an elevated role.

{
  "statusCode": 401,
  "message": "Unauthorized - Invalid or missing token"
}

{
  "statusCode": 401,
  "message": "Unauthorized - Invalid or missing token"
}

{
  "statusCode": 401,
  "message": "Unauthorized - Invalid or missing token"
}

Best practices

Treat JWTs and API keys as secrets: never log them, never put them in URL query strings, and rotate them if exposure is suspected. Contact your Valpay representative to issue or rotate API keys.