Authentication

Orbi uses API keys to authenticate API requests. Your API keys grant access to sensitive resources and operations, so it is critical to keep them secure at all times.

Getting Your API Keys

To generate an API key:

Log in to your Orbi One Dashboard
Navigate to Payment Gateway → Settings → API Keys
Click Generate New API Key
Select the environment (Production or Sandbox)
Configure the required permissions and restrictions
Copy and securely store your API key — it will be displayed only once

You can identify the environment of an API key by its prefix:

ak_sandbox_ — Sandbox (development and testing)

ak_live_ — Production

Authentication

Authenticate requests by including your API key in the x-api-key request header.

Example Request

curl -X GET https://sandbox.orbipayments.com/v1/orders/ord_xxxxxxx \
  -H "x-api-key: ak_sandbox_xxxxx..."

API Key Security

Best Practices

To keep your integration secure, follow these guidelines:

Never expose API keys in client-side code, URLs, or public repositories
Store API keys in environment variables or secure secret managers
Rotate API keys regularly, especially after personnel or infrastructure changes
Use separate API keys per environment (sandbox, staging, production)
Restrict permissions to the minimum required for each key

Example: Secure Storage

// ✅ Recommended: Use environment variables
const apiKey = process.env.ORBI_PG_API_KEY;

// ❌ Not recommended: Hardcoding secrets
const apiKey = "ak_live_1234567890abcdef";

API Key Permissions (Scopes)

API keys use scopes to define which actions are permitted. Each scope grants access only to resources owned by the authenticated merchant.

Available Scopes

Scope	Description
`merchant:self:read`	Read information about the authenticated merchant, including profile and configuration.
`orders:self:create`	Create new orders for the authenticated merchant.
`orders:self:read`	Retrieve and list orders belonging to the authenticated merchant.
`orders:self:update`	Update existing orders (for example, metadata or allowed status transitions).
`orders:self:delete`	Delete orders when permitted by business rules.
`payments:self:read`	Retrieve and list payments associated with the authenticated merchant.
`webhooks:self:create`	Create webhook endpoints for the authenticated merchant.
`webhooks:self:read`	Retrieve and list webhook endpoints.
`webhooks:self:update`	Update webhook endpoint configuration, including subscribed events and active status.
`webhooks:self:delete`	Delete webhook endpoints.

Note
All self scopes are strictly limited to resources owned by the authenticated merchant. Cross-merchant access is not permitted under any circumstance.

Troubleshooting

Invalid API Key

Returned when the provided API key is missing, malformed, or does not exist.

{
  "error": "Unauthorized",
  "message": "Invalid API key provided",
  "statusCode": 401
}

Insufficient Permissions

Returned when the API key does not have the required scope for the requested operation.

{
  "error": "Forbidden",
  "message": "Insufficient scope",
  "statusCode": 403
}

Rate Limit Exceeded

Returned when too many requests are made in a short period of time.

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "statusCode": 429
}