Skip to main content

Authentication

Learn how to authenticate with the GCA Pay API using Bearer tokens.

Overview​

GCA Pay API uses Bearer token authentication for all requests. After completing registration and KYC through the merchant dashboard, you'll receive API credentials for your approved projects.

Account Setup Required

Registration and KYC verification are completed through the GCA Pay Merchants Dashboard. API tokens are provided after approval.

Getting API Tokens​

  1. Complete Registration: Register through the merchant dashboard
  2. Submit KYC: Upload required business documents
  3. Create Project: Set up your integration project
  4. Get Credentials: Receive API tokens for sandbox and production

Required KYC Documents​

  • Certificate of Incorporation
  • Business License
  • Tax Identification Number (TIN)
  • Board Resolution Letter

Token Types​

Sandbox Tokens​

  • Used for testing and development
  • Safe environment with simulated transactions
  • No real money movement

Production Tokens​

  • Used for live transactions
  • Real money movement
  • Requires completed KYC approval

Using Bearer Tokens​

Include your API token in the Authorization header of every request:

Authorization: Bearer YOUR_API_TOKEN
POST /user-service/login

Request Body​

{
  "email": "[email protected]",
  "password": "your_password"
}

Response​

{
  "success": true,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": 123,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "user_type": "Merchant",
    "kyc_status": "approved"
  }
}

Using the Authentication Token​

Include the token in the Authorization header for all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Request​

GET /user-service/users/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

OTP Verification​

Some sensitive operations may require OTP verification:

Request OTP​

POST /user-service/request-otp
Authorization: Bearer your_token
Content-Type: application/json

{
  "phone_number": "+255683542710",
  "purpose": "transaction_verification"
}

Verify OTP​

POST /user-service/verify-otp
Authorization: Bearer your_token
Content-Type: application/json

{
  "phone_number": "+255683542710",
  "otp_code": "123456"
}

Password Reset​

Request Password Reset​

POST /user-service/forgot-password
Content-Type: application/json

{
  "email": "[email protected]"
}

Reset Password​

POST /user-service/reset-password
Content-Type: application/json

{
  "email": "[email protected]",
  "reset_token": "token_from_email",
  "new_password": "NewSecurePassword123"
}

Token Management​

Token Expiration​

  • Access tokens expire after 1 hour (3600 seconds)
  • Always check the expires_in field in the login response
  • Implement token refresh logic in your application

Best Practices​

  1. Store tokens securely - Never expose tokens in client-side code
  2. Implement token refresh - Automatically refresh tokens before expiration
  3. Handle token errors - Gracefully handle 401 Unauthorized responses
  4. Use HTTPS only - Never send tokens over unencrypted connections

Error Handling​

{
  "success": false,
  "error": "invalid_token",
  "message": "The access token is invalid or expired"
}

Common authentication errors:

  • invalid_credentials - Wrong email/password
  • invalid_token - Token is malformed or expired
  • token_expired - Token has expired
  • insufficient_permissions - User doesn't have required permissions

Security Considerations​

  1. Rate Limiting: Login attempts are rate-limited to prevent brute force attacks
  2. Token Rotation: Implement regular token refresh in production
  3. Secure Storage: Use secure storage mechanisms for tokens
  4. Environment Variables: Store sensitive credentials in environment variables
  5. Audit Logging: All authentication events are logged for security monitoring