Skip to main content

Token Lifecycle

Understanding how to manage your access tokens effectively.

Token expiry​

Access tokens expire after 1 hour (3600 seconds). When your token expires, you need to:

  1. Generate a new JWT assertion (with a new jti).
  2. Exchange it for a new access token.

There is no refresh token mechanism -- you simply perform a new token exchange each time.

Don't wait for a 401 response. Instead, track the expiresIn value and proactively refresh your token before it expires.

Token Timeline

|---- issued ----|---- use token ----|---- refresh here ----|---- expires ----|
0 min                              50 min                   60 min

We recommend refreshing at the 50-minute mark (or when ~80% of the token lifetime has elapsed). This gives you a comfortable buffer and avoids failed requests.

Example: Token manager pattern​

A common pattern is to build a token manager that handles caching and automatic refresh:

class TokenManager:
    - Stores the current access token and its expiry time
    - On getToken():
        - If token exists and is not near expiry, return cached token
        - Otherwise, perform a new token exchange
        - Cache the new token and expiry time
        - Return the new token

See the Code Examples section for working implementations of this pattern.

What happens when a token expires​

If you use an expired token, the API gateway will return:

HTTP/1.1 401 Unauthorized

Simply perform a new token exchange and retry the request.

Clock skew​

RynoPay allows a 30-second clock skew when validating JWT timestamps. However, we strongly recommend keeping your server clock accurate using NTP to avoid any issues.