Authentication

All API requests require authentication using an API key. The key must be included in the Authorization header of every request using the Bearer token scheme. Unauthenticated requests return a 401 Unauthorized error.

Authentication Method

Martis uses Bearer token authentication. Include the API key in the Authorization header:

curl https://api-staging.martis.id/api/v1/payments/charges \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'Content-Type: application/json'

Header Format

Authorization: Bearer <API_KEY>

Replace <API_KEY> with the secret key obtained from the dashboard. See API Keys for key generation instructions.

Environment-Specific Authentication

API keys are scoped to specific environments. Requests must use the correct API key for the target environment.

Error Responses

Authentication failures return one of the following responses:

401 Unauthorized

Returned when the API key is missing, invalid, or expired.

{
  "status": "error",
  "message": "Invalid or missing API key"
}

Common causes:

• Missing Authorization header
• Incorrect API key
• Revoked API key
• Environment mismatch (sandbox key used with production API)

403 Forbidden

Returned when the API key is valid but lacks permission for the requested action.

{
  "status": "error",
  "message": "Insufficient permissions for this action"
}

Common causes:

• API key lacks required feature access
• Account not activated for the requested operation
• IP address not in the allowlist (when IP restrictions are enabled)

Security Best Practices

Key Protection

• Server-side only — Never include API keys in client-side code, mobile apps, or browser JavaScript
• Environment variables — Store keys in environment variables, not in source code
• Secrets management — Use a dedicated secrets manager for production environments
• Version control — Never commit API keys to repositories; use .gitignore to exclude environment files

Access Control

• Minimal permissions — Request only the access levels required for each integration
• Separate keys — Use different API keys for different services or environments
• Regular rotation — Rotate keys periodically (recommended: every 90 days)
• Prompt revocation — Revoke keys immediately upon suspected compromise

Network Security

• HTTPS only — All API requests must use HTTPS; HTTP requests are rejected
• IP restrictions — Configure IP allowlists for production API keys
• Request logging — Monitor API usage for unusual patterns

Request Example

A complete authenticated request includes the Authorization header and appropriate content headers:

curl https://api-staging.martis.id/api/v1/payments/charges \
  --request POST \
  --header 'Authorization: Bearer sk_test_abc123xyz...' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment_method": "qris",
    "channel": "gudang_voucher",
    "amount": 50000,
    "currency": "idr",
    "customer_details": {
      "email": "customer@example.com"
    }
  }'

SDK Authentication

When using official SDKs, configure the API key during client initialization:

const martis = require('martis')({
  apiKey: process.env.MARTIS_API_KEY,
  environment: 'sandbox' // or 'production'
});

Troubleshooting