Skip to main content

​
Authentication

The Issuing API uses RSA-signed JWT tokens for authentication. To authenticate requests, you need:
  1. An Access Key (UUID) - obtained from your implementation manager
  2. An RSA key pair - you generate this yourself
  3. JWT signing - sign each request with your private key
For detailed implementation instructions, see the Request Signing guide which covers the complete authentication flow including JWT token generation and signing.

​
Overview

Authentication works by:
  1. Registering your public key - Email your RSA public key to your implementation manager to receive an Access Key
  2. Signing requests - For each API request, create a JWT token signed with your RSA private key
  3. Including the token - Add the signed JWT to the Authorization header as a Bearer token

​
Quick Example

curl https://access.utgl.io/v1/ping \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
The Bearer token is a JWT that includes:
  • Your Access Key (sub claim)
  • Request URI (uri claim)
  • HTTP method (method claim)
  • Request body hash (body claim, if applicable)
  • Timestamps (iat, exp claims)
Security Best Practices:
  • Never share your private key or commit it to version control
  • Store keys securely in encrypted storage
  • Use environment variables for sensitive credentials
  • Rotate keys periodically
  • Keep JWT tokens short-lived (expire within 30 seconds)

​
Authentication Errors

If authentication fails, you’ll receive a 401 Unauthorized response: 
{
  "code": "INVALID_SIGNATURE",
  "message": "JWT signature verification failed"
}
Common authentication errors:
Error CodeDescriptionSolution
INVALID_SIGNATUREJWT signature verification failedVerify your private key and signature algorithm
Authentication failedInvalid or missing access keyCheck your access key is correct
Authentication failedJWT token expiredEnsure token is less than 30 seconds old

​
Sandbox Convenience

In the sandbox environment, you can use HTTP Basic Authentication as a convenience (no signature required): 
curl -u YOUR_ACCESS_KEY: https://sandbox.access.utgl.io/v1/ping
In production, RSA-signed JWT tokens are required. See Sandbox Environment for details.

​
Rate Limiting

Authenticated requests are subject to rate limiting. See our Rate Limits documentation for details.

​
Next Steps