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
const loginData = await loginResponse.json();
if (loginData.token) {
const bearerToken = loginData.token;
// Extract refresh token from response headers
const refreshToken = loginResponse.headers.get('x-auth-refresh-token');
}
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"
// Note: This code should run on the server-side to prevent CORS issues
const authUrl = `https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod/login`;
// In this example, we assume the refresh token is stored securely on the server
const storedRefreshToken = getStoredRefreshToken(); // Your secure storage method
if (!storedRefreshToken) {
throw new Error('No refresh token available - user needs to log in');
}
const refreshResponse = await fetch(authUrl, {
method: 'GET',
cache: 'no-cache',
credentials: 'include',
headers: {
'Content-Type': 'application/json',
'x-auth-refresh-token': storedRefreshToken
}
});
const refreshData = await refreshResponse.json();
if (refreshData.token) {
const newBearerToken = refreshData.token;
// Save new refresh token if provided
const newRefreshToken = refreshResponse.headers.get('x-auth-refresh-token');
if (newRefreshToken) {
saveRefreshToken(newRefreshToken); // Your secure storage method
}
}
Response example
200 OKresponse.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-tokenheader 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 docs
- Login guide: Log in as user
- Full authentication guide: Authentication flow
Related
Authentication flowChange user passwordGet user dataGet user ordersLog in userLog out userRefresh user tokenRegister userReset user passwordSubscribe to newsletterUpdate user data