Build a JWT Assertion

The JWT assertion is a short-lived, signed token that proves your identity to RynoPay. You create it on your server and send it to the token endpoint.

JWT Header

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "<your-api-key-id>"
}

Field	Value	Description
alg	ES256	ECDSA with P-256 curve
typ	JWT	Standard JWT type
kid	Your API Key ID (UUID)	The ID displayed when you registered your public key

JWT Payload (Claims)

{
  "iss": "<your-partner-id>",
  "sub": "<your-partner-id>",
  "aud": "https://prod.rynopay.io/auth/partner/v1/token",
  "exp": 1700000300,
  "iat": 1700000000,
  "jti": "550e8400-e29b-41d4-a716-446655440000"
}

Claim	Required	Description
iss	Yes	Your Partner ID (UUID)
sub	Yes	Must be the same as iss (your Partner ID)
aud	Yes	Must be exactly https://prod.rynopay.io/auth/partner/v1/token
exp	Yes	Expiration time (Unix timestamp). Maximum 5 minutes after iat
iat	Yes	Issued-at time (Unix timestamp). Should be the current time
jti	Yes	A unique ID for this request. Must be unique for every request

Unique jti required

Every JWT assertion must have a unique jti value. We recommend using a UUID v4. Reusing a jti will be rejected as a replay attack.

Sign the JWT

Sign the complete JWT (header.payload) using your private key with the ES256 algorithm. The result is a three-part base64url-encoded string:

eyJhbGciOi...header...eyJpc3MiOi...payload...signature

This is your assertion. You will send it to the token exchange endpoint in the next step.

Checklist

Before sending your assertion, verify:

• kid in the header matches your API Key ID from the Partner Portal
• iss and sub are both set to your Partner ID
• aud is exactly https://prod.rynopay.io/auth/partner/v1/token
• exp is no more than 5 minutes after iat
• jti is a fresh, unique value
• The JWT is signed with your private key using ES256

See Code Examples for complete working implementations.