Overview
Thetokens sub-client handles the token lifecycle: exchanging authorization codes for grant tokens, verifying tokens via the API, and revoking tokens.
tokens.exchange()
Exchange an authorization code for a signed grant token (RS256 JWT).Parameters
The PKCE code verifier. Required if
codeChallenge was provided in the authorize step. See PKCE.Response: ExchangeTokenResponse
tokens.refresh()
Refresh a grant token using a refresh token while the underlying grant remains active. Returns a new grant token and a new refresh token. ThegrantId and expiresAt stay the same.
Refresh tokens are single-use and rotated on every refresh per SPEC ยง7.4. Refresh does not extend the grant lifetime; after expiresAt, the caller must re-authorize. If the HTTP response is lost after commit, retry the same previous refresh token with the same idempotency key. During a five-minute window, Grantex returns the already-rotated refresh token instead of rotating again. After that window, or once the rotated child token has been used, the previous token is rejected.
Parameters
A 16-256 character key that identifies this logical refresh attempt. The SDK
retains an automatically generated key for five minutes in the current
process. Supply and persist this field when recovery must survive a caller
restart or failover.
Response: ExchangeTokenResponse
Returns the same shape as exchange() โ see above for field descriptions.
tokens.verify()
Verify a grant token online via the Grantex API. This is useful when you want server-side validation without managing JWKS yourself.Parameters
Response: VerifyTokenResponse
For local signature-and-claim verification without the online revocation
endpoint, use verifyGrantToken().
The standalone helper still resolves the remote JWKS on each call.
tokens.revoke()
Revoke a token by its token ID (thejti claim). The API responds with 204 No Content.
Parameters
Response
Returnsvoid. The token is immediately invalidated.