Authentication

Gerbang Pay supports two authentication methods:

Method	Used By	Endpoints
API Key	Client applications (payment flow)	/v1/payments/*, /v1/active-methods
JWT RS256	Dashboard / user login	All management endpoints

---

API Key

API Keys are used by your client applications to create and retrieve payment data.

How to Generate an API Key

1. Log in to the Gerbang Pay Dashboard
2. Go to the Settings → API Keys menu
3. Click Generate New API Key
4. Choose the mode: Live or Test
5. Save the key that appears — the key is only displayed once

Header Format

Authorization: ApiKey {api_key}

⚠️ Important: The authentication format for API Keys uses the prefix ApiKey, not Bearer. Using Bearer with an API Key will result in a 401 Invalid JWT token error.

Live Key vs Test Key

Key Type	Format	Provider Environment
Live Key	gp_live_...	Production (real transactions)
Test Key	gp_test_...	Sandbox (simulated transactions)

The system automatically determines whether a payment is routed to the Production or Sandbox environment based on the key type used. You do not need to change your code or endpoint URLs.

Example Request with API Key

curl -X POST https://gerbang-pay-api.gai.co.id/v1/payments/create \
  -H "Authorization: ApiKey gp_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-12345" \
  -d '{
    "amount": 10000000,
    "currency": "IDR",
    "method_type": "virtual_account",
    "method_detail": { "type": "virtual_account", "bank": "BCA" }
  }'

---

JWT (RS256) — For Dashboard

JWT is used for management operations: managing tenants, API keys, provider configurations, viewing reports, etc.

The JWT token uses the RS256 algorithm and contains the claims sub (tenant ID), role, and tier.

Login

POST /v1/auth/login

Request Body:

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

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiJ9...",
    "refresh_token": "rt_xxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

Refresh Token

POST /v1/auth/refresh

Request Body:

{
  "refresh_token": "rt_xxxxxxxxxxxxxxxx"
}

Logout

POST /v1/auth/logout

Request Body:

{
  "refresh_token": "rt_xxxxxxxxxxxxxxxx"
}

Using JWT

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Reset Password

If you forget your password:

POST /v1/auth/password-reset/request

{
  "tenant_id": "your-tenant-uuid",
  "email": "[email protected]"
}

Then confirm the reset with the received token:

POST /v1/auth/password-reset/confirm

{
  "token": "reset_token_from_email",
  "new_password": "new_password_min_8_chars"
}

---

Endpoints vs Authentication Methods

Endpoint	API Key	JWT
POST /v1/payments/create	✅ (requires Client role)	❌
GET /v1/payments/{id}	✅	✅
POST /v1/payments/{id}/cancel	✅	✅
GET /v1/active-methods	✅	✅
GET /v1/payments/{id}/ledger	✅	✅
POST /v1/auth/login	❌ (public)	❌ (public)
POST /v1/auth/refresh	❌ (public)	❌ (public)
GET /v1/tenants/*	❌	✅ (Owner/Partner)
POST /v1/tenants/*/api-keys	❌	✅

💡 Note: Only tenants with the Client role can create payments. Tenants with Owner or Partner roles cannot call POST /v1/payments/create.

---

API Key Security

• API Keys are stored as hashes (HMAC-SHA256) in the database — their original values cannot be recovered.
• If a key is leaked, immediately revoke it from the dashboard and generate a new key.
• Never place API Keys in a frontend/browser environment where users can inspect them.
• Use environment variables to store API Keys on your server.