Access to the Issuing API is authenticated using an API access key combined with cryptographically signed API requests.Documentation Index
Fetch the complete documentation index at: https://developer.utgl.io/llms.txt
Use this file to discover all available pages before exploring further.
Overview
To authenticate your implementation against the Issuing API, you must complete three steps:- Generate an RSA key pair - Create a public/private RSA key pair in PEM format (minimum 2048 bits)
- Register your public key - Email your public key and IP whitelist address to your implementation manager. In return, you’ll receive an Access Key (UUID). In the future, this can be done via the UTGL Developer Portal.
- Sign your requests - Use your access key and private key to generate signed JWT tokens for each API request
Authentication Flow
The following diagram illustrates the complete authentication flow from initial setup to making authenticated API requests:Step 1: Generate RSA Key Pair
Generate a public/private RSA key pair using OpenSSL or your preferred tool.Step 2: Create Bearer Token
Each API request requires a Bearer token in theAuthorization header. The token is a signed JWT that includes request-specific claims.
Process Overview
- Create the JWT header and payload - Include required claims (URI, method, body hash, etc.)
- Sign the JWT - Use your RSA private key with the RS256 algorithm
- Add to request header - Include the signed token as
Authorization: Bearer <token>
JWT Creation Process
JWT Token Specification
The JWT token must be created according to the following specification.Header
The JWT header must contain:| Field | Value | Description |
|---|---|---|
alg | RS256 | Signature algorithm |
typ | JWT | Token type |
Payload (Claims)
The JWT payload must include the following claims:| Claim | Required | Description | Example |
|---|---|---|---|
sub | Yes | Your Access Key (UUID) | 899a7a89-bb6b-4d43-a702-c6aa45dd89cf |
iat | Yes | Issued at time (Unix timestamp in seconds) | 1668849961 |
exp | Yes | Expiration time (Unix timestamp in seconds). Must be less than iat + 30 seconds | 1668849991 |
body | Conditional | Hex-encoded SHA-256 hash of the raw HTTP request body. Optional for GET requests (empty body) | 93a23971a914e5eacbf0a8d25154cda309c3c1c72fbb9914d47c60f3cb681588 |
uri | Yes | The URI part of the request, including query parameters | /v1/transactions?filter=123 |
method | Yes | The HTTP method of the request | GET, POST, PUT, DELETE |
Signing
The JWT must be signed using your RSA Private Key with the RS256 algorithm.Example: GET Request
The following example demonstrates how to create a JWT for a GET request to/ping.
Test Credentials
JWT Components
Example: POST Request
The following example demonstrates how to create a JWT for a POST request with a request body.Request Details
- Endpoint:
POST /ping - Request Body:
{"hello":"world"} - Access ID:
ed63e5a1-3e8e-4b63-96b5-b711f91bc2dd
JWT Components
Important: The
body claim contains the hex-encoded SHA-256 hash of the raw request body. For POST requests, you must include this hash. The exact string representation of the body must match between signing and sending.Common Issues & Troubleshooting
Token Expiration
JWT tokens expire after 30 seconds. Generate a fresh token for each API request.Body Hash Mismatch
Ensure the request body used for signing exactly matches the body sent in the HTTP request. Common issues:- Trailing whitespace differences
- JSON formatting differences (spaces, newlines)
- Character encoding mismatches
Invalid Signature Errors
If you receiveINVALID_SIGNATURE errors:
- Verify your private key is correct and properly formatted
- Ensure you’re using RS256 algorithm
- Check that all required claims are present
- Verify the
uriincludes query parameters if present - Confirm the
bodyhash matches the actual request body (for POST requests)
Next Steps
- Review language-specific authentication guides for implementation examples
- Explore the API Reference to see available endpoints
- Check Error Handling for detailed error responses