Authentication

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.

RS256(Recommend)

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 a RSA key pair

JWT Payload Example (RS256)

When using the RS256 algorithm (asymmetric signing with RSA), the payload structure remains the same as with HS256. A typical JWT payload includes the following claims:

{
  "iss": "6A909655CF67444A93262A665CDD235F",
  "exp": 1718236800
}

Note: 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 a update plan and timeline for transitioning to the RS256 algorithm, in alignment with enhanced security standards.

Account Setup

When you're ready to connect to our sandbox environment, DragonPass will assist in account setup and provide the necessary credentials for JWT generation:

Issuer (iss): 6A909655CF67444A93262A665CDD235F
A unique issuer identifier will be assigned to your account. This identifier must be used when generating JWTs to ensure they are valid for API endpoints.

Secret Key: 60B118779DD14B0990692B51BF8B93DC
A new, unique secret key will be generated for your account. This key is used to sign the JWTs, ensuring that they are secure and have not been tampered with.

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": "6A909655CF67444A93262A665CDD235F",
  "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.

Request

{
    "clientId": "DragonPass", // issuer
    "secret": "dpSecretKey12345"
}

Response

{
  "code": 0,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "validUntil": 1923263999
  }
}

The returned token is valid for 1 hour.

RS256(Recommend)#

Account Setup and Credential Generation#

Key Exchange Flow#

Example: Generate RSA Key Pair Using OpenSSL#

JWT Payload Example (RS256)#

HS256#

Account Setup#

JWT Self-Generation#

Example Snippet (Java)#

Token Generation via API#

RS256(Recommend)

Account Setup and Credential Generation

Key Exchange Flow

Example: Generate RSA Key Pair Using OpenSSL

JWT Payload Example (RS256)

HS256

Account Setup

JWT Self-Generation

Example Snippet (Java)

Token Generation via API