Authentication flow

The Geins platform provides a secure authentication system for user management using a signature-based authentication flow. This guide explains the authentication concepts, flow, and available functions for managing user sessions in your application.

Overview

The authentication process in Geins follows a two-step signature-based approach that ensures secure transmission of credentials without exposing sensitive data:

1. Challenge request: Send username to get a signature challenge
2. Credential verification: Send back the signed credentials with password/action data
3. Token management: Receive and manage Bearer tokens and refresh tokens

This method prevents credential exposure, replay attacks, and provides a robust foundation for user session management.

Tokens

• Bearer token: Short-lived JWT token for API authentication (by default 15 minutes)
• Refresh token: Longer-lived token for obtaining new Bearer token (by default 7 days)

Authentication endpoints

The Geins authentication system uses two main endpoints:

• Auth Service: https://auth-service.geins.io/api/{ACCOUNT_NAME}_prod
• Signature Service: https://merchantapi.geins.io/auth/sign/{MERCHANT_API_KEY}

Authentication functions

The authentication system supports five main functions for user management:

Registration

Create new user accounts and establish initial authentication sessions.

Purpose: Register new users with username/email and password
Endpoint: POST /register
Flow: Challenge → Signature → Registration with credentials → Commit user to Merchant API Result: New user account + Bearer token + Refresh token

Login

Authenticate existing users and establish active sessions.

Purpose: Verify user credentials and create authenticated session
Endpoint: POST /login
Flow: Challenge → Signature → Authentication with credentials
Result: Bearer token + Refresh token for authenticated requests

Password change

Allow users to securely update their passwords while maintaining active sessions.

Purpose: Change user password with current password verification
Endpoint: POST /password
Flow: Challenge → Signature → Password change with current + new password
Result: New Bearer token + Refresh token (old tokens invalidated)

Token refresh

Maintain sessions by refreshing expired or soon-to-expire bearer tokens using refresh tokens.

Purpose: Get new bearer token when current token expires or is about to expire
Endpoint: GET /login (with refresh token header)
Flow: Send refresh token → Receive new bearer token
Result: New bearer token + New refresh token

Logout

Securely terminate user sessions and invalidate all tokens.

Purpose: End user session and invalidate authentication tokens
Endpoint: GET /logout
Flow: Send refresh token → Server invalidates tokens
Result: Session terminated, tokens invalidated

Security considerations

• HTTPS only: All authentication requests must use HTTPS
• Server-side processing: Handle all auth requests server-side to prevent CORS issues
• Secure storage: Store refresh tokens in HTTP-only cookies or secure server-side storage
• Proper cleanup: Clear all tokens on logout and session timeout

Merchant API integration

To use the Geins Merchant API with authenticated users, include the Bearer token in the Authorization header of your requests:

{
  "Authorization": "Bearer {BEARER_TOKEN}"
}