How to

Refresh user token

Refresh the Bearer token for Geins Merchant API access using Geins Auth Service

Prerequisites

  • Valid customer credentials (username/email and password)
  • Merchant API key

Goal

  • Refresh expired Bearer tokens seamlessly
  • Maintain user session without requiring re-login
  • Get new Bearer token for continued API access

Architecture at a glance

  • Save refresh token on log in → Use stored refresh token to get new Bearer token → save new refresh token → continue API requests

APIs used

  • Auth Service: https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login (GET request for refresh)
Refresh tokens are provided in the x-auth-refresh-token header during login and must be stored securely for future refresh requests.
Important: All calls to the auth service must be handled from the server-side to prevent CORS issues. Do not make direct calls to the auth service from client-side code.

When to refresh

  • Before expiration: Bearer tokens expire after 15 minutes
  • On 401 errors: When API calls return unauthorized
  • Proactively: Check token expiration before making requests

Step-by-step

Save refresh token during login

Learn more about how to login a customer here.

When logging in, extract and store the refresh token from response headers:

# Extract refresh token from response headers when logging in
curl -X POST "https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login" \
  -H "Content-Type: application/json" \
  -D headers.txt \
  -d '{
    "username": "{USER_EMAIL}",
    "password": "{USER_PASSWORD}",
    "signature": { ... }
  }'

# Extract the refresh token from headers
grep "x-auth-refresh-token" headers.txt

Check if token needs refresh

Use the token maxAge or expiration time to determine if a refresh is needed before making API calls. If the token is expired or about to expire, proceed to refresh.

Refresh the token

Use the stored refresh token to get a new Bearer token:

Request example

curl -X GET "https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login" \
  -H "Content-Type: application/json" \
  -H "x-auth-refresh-token: {REFRESH_TOKEN}" \
  -H "Cache-Control: no-cache"

Response example

200 OK
response.json
{
  "token": "NEW_JWT_TOKEN",
  "maxAge": 900
}

Security and access

  • Store refresh tokens securely (cookies, sessionStorage, localStorage).
  • Always use HTTPS for refresh requests.
  • Clear refresh tokens on logout or when they become invalid.
  • Handle refresh failures gracefully by redirecting to login.

Common pitfalls

  • Not saving the refresh token from the x-auth-refresh-token header during login.
  • Forgetting to update stored refresh token when a new one is provided during refresh.
  • Not handling refresh failures - users get stuck with expired tokens.
  • Refreshing too frequently - check expiration before refreshing unnecessarily.
Related