API Key Authentication

API Keys provide permanent, server-to-server authentication for the SUIT Billing API. They are the recommended method for backend integrations and automated workflows.

Format

API Keys follow the format sk_live_ followed by a random string:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Usage

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

curl -X POST https://api.suit.pe/api/invoices \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Obtaining an API Key

API Keys are created when your tenant is provisioned. Additional keys can be created via the admin API:

curl -X POST https://api.suit.pe/admin/tenants/TENANT_ID/api-keys \
  -H "Authorization: Bearer ADMIN_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my-integration"
  }'

Response:

{
  "id": "key_abc123",
  "label": "my-integration",
  "key": "sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "createdAt": "2026-02-20T00:00:00.000Z"
}

The key value is only returned at creation time. Store it securely — it cannot be retrieved later.

Managing API Keys

List keys

curl https://api.suit.pe/admin/tenants/TENANT_ID/api-keys \
  -H "Authorization: Bearer ADMIN_MASTER_KEY"

Revoke a key

curl -X DELETE https://api.suit.pe/admin/tenants/TENANT_ID/api-keys/KEY_ID \
  -H "Authorization: Bearer ADMIN_MASTER_KEY"

Security best practices

Store API Keys in environment variables, never in source code or version control
Use different API keys for different integrations (label them for tracking)
Rotate keys periodically
Revoke compromised keys immediately
Only use API Keys in server-side code — never expose them in client-side JavaScript

Scope

API Keys have access to all /api/* endpoints:

Document emission (invoices, receipts, credit notes, etc.)
Document queries and downloads (PDF, XML, CDR)
Client and product catalogs
Receivables and payments
Reports and exports

API Keys do not have access to:

/auth/* endpoints (login, refresh)
/admin/users endpoints (user management)
/admin/tenants endpoints (tenant management — requires Master Key)