Our API uses JSON Web Tokens (JWT) for secure authentication, providing efficient and reliable access while maintaining strong security standards.To generate a JWT, you'll need to use a library that supports JWT creation and validation. You can visit jwt.io to find libraries and examples specific to your programming environment.Please ensure that you securely store the secret key and do not expose it in your client-side code.
We recommend transitioning from HS256 to RS256 for enhanced security. We also suggest that clients provide their public key for verification purposes.
Credential Management and Rotation#
Credentials are managed at the permission-group level. Each permission group supports a maximum of two credentials at the same time.For E-Pass, one permission group maps to one Program ID.
For Membership, one permission group may map to multiple Program IDs.
The two credentials may use different algorithms. For example, one credential may use HS256 while the other uses RS256.
Credential Validity and Rotation#
Each credential has a configurable validity period. The Dragonpass API platform supports seamless credential rotation without service interruption.Customers that rotate credentials regularly can activate a new credential before the current credential expires. During the transition period, both credentials remain valid in parallel, allowing traffic to be migrated to the new credential before the previous credential is retired.Do not use a credential after its validity period has ended.
JWT Payload#
Every JWT must include iss, keyid, and exp.{
"iss": "YOUR_ISSUER",
"keyid": "key_0001_20260101_20261231_a",
"exp": 1718236800
}
iss: The issuer value provided during account setup.
keyid: Identifies the credential used to sign the JWT.
exp: A Unix timestamp indicating when the JWT expires.
key_{projectId}_{validFrom}_{validUntil}_{credentialSlot}
key_0001_20260101_20261231_a
{tenantId} is the project identifier.
{validFrom} is the start of the credential validity period.
{validUntil} is the end of the credential validity period.
{credentialSlot} is a or b, identifying one of the two credentials available to the permission group.
RS256 (Recommended)#
Account Setup and Credential Generation#
Once you're ready to connect to our sandbox environment, you will be required to generate an RSA key pair and share the public key with Dragonpass.Once Dragonpass receives the public key, we will configure the necessary endpoint permissions and issue the issuer value for the client to use when generating JWTs.Key Exchange Flow#
Example: Generate RSA Key Pair Using OpenSSL#
Here is an example of generating an RSA key pairNote: iss (issuer) will be provided by Dragonpass. exp (expiration) should be a Unix timestamp indicating when the token expires.
HS256#
Clients currently utilizing HS256 for JWT authentication may continue using this algorithm without service interruption. Dragonpass will engage with each client to coordinate an update plan and timeline for transitioning to the RS256 algorithm, in alignment with enhanced security standards.
JWT Self-Generation#
Once your JWT library is set up, you can generate your own token by including the required claims and signing it using your secret key.The payload typically includes the following claims:{
"iss": "YOUR_ISSUER",
"keyid": "key_0001_20260101_20261231_a",
"exp": 1718236800
}
Example Snippet (Java)#
Token Generation via API#
Alternatively, you can request a token directly from our API using your credentials.
Call the Generate Access Token endpoint and include your clientId (issuer) and secret in the request body.{
"clientId": "Dragonpass",
"secret": "dpSecretKey12345"
}
{
"code": 0,
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"tokenType": "Bearer",
"validUntil": 1923263999
}
}
The returned token is valid for 1 hour.
