Token types
| Token | Lifetime | Purpose |
|---|
idToken / access_token | ~1 hour | Bearer token for API calls |
refreshToken / refresh_token | Long-lived | Exchange for a new access token without re-authenticating |
Refreshing tokens
When your idToken expires, exchange the refreshToken for a new pair:
curl -s -X POST https://api.zeam.money/gw/v1/public/auth/refresh \
-H 'Content-Type: application/json' \
-d '{"refreshToken": "'$REFRESH_TOKEN'"}'
{
"idToken": "eyJhbGciOi...",
"refreshToken": "bmV3IHJlZnJl...",
"expiresIn": 3600
}
Update both idToken and refreshToken atomically when you refresh. The old refreshToken is invalidated after use.
Expiry handling
- Check the
expiresIn field (seconds) to know when the token will expire
- Refresh proactively before expiry to avoid failed requests
- If a request returns
401, your token has expired — refresh and retry
OAuth tokens
OAuth-authenticated users refresh their tokens through the OAuth provider client SDK. The Zeam API does not issue or manage refresh tokens for OAuth principals.
Best practices
- Store tokens securely — treat refresh tokens like passwords
- Refresh proactively — don’t wait for a
401
- Update atomically — never use a stale refresh token
- Handle re-authentication — if refresh fails, prompt the user to sign in again
