API Keys

Overview

API keys are managed through the EQUOS subscriber console under Integrations → API Keys. Each key is an OAuth 2.0 machine-to-machine credential for server-to-server calls to /e9v3.

Authentication: These management endpoints require a signed-in account admin (Firebase ID token). They are separate from the M2M JWT you use on /e9v3.

Business tenancy

One API key binds to one business by default. When you exchange a classic key for a token and call /e9v3, EQUOS resolves the tenant from the key itself. Do not send X-Business-ID (or a businessId query) on public API requests for those keys — the header is ignored for tenancy.

• In the console, use the business picker at the top of Integrations to choose which business you are managing, then generate or revoke keys for that business.
• Multi-business account admins can still mint one key per business (you do not need to change your default claim first — pass businessId on the admin API, or pick the business in the UI). Existing keys keep working this way.
• Optionally, select additional owned businesses when minting to create a multi-business key. Those keys require X-Business-ID on every /e9v3 call; the value must be one of the businesses bound at create time. Missing header → 400 businessId required; unbound id → 403 key not bound to business. Revoking that key from any one bound business stops it working for all of them.

[
  {
    "id": "key-uuid-1",
    "businessId": "biz_equos_demo",
    "name": "Production Integration",
    "prefix": "abc12345",
    "scopes": ["orders:write"],
    "createdAt": "2024-01-15T10:00:00Z",
    "expiresAt": null,
    "isActive": true
  },
  {
    "id": "key-uuid-2",
    "businessId": "biz_equos_demo",
    "name": "Staging Integration",
    "prefix": "def67890",
    "scopes": ["orders:read", "orders:write"],
    "createdAt": "2024-01-10T15:30:00Z",
    "expiresAt": "2025-01-10T00:00:00Z",
    "isActive": true
  }
]

{"error": "no businessId in user claims"}

{"error": "not authorized for business"}

{
  "id": "key-uuid-3",
  "businessId": "biz_equos_demo",
  "name": "New Integration",
  "prefix": "ghi11111",
  "scopes": ["orders:write"],
  "createdAt": "2024-01-20T12:00:00Z",
  "expiresAt": null,
  "isActive": true,
  "clientId": "your_client_id",
  "clientSecret": "secret_abc123def456..."
}

{"error": "at least one scope is required"}

{"error": "no businessId in user claims"}

{"error": "not authorized for business"}

{
  "ok": true
}

{"error": "api key not found"}

{"error": "no businessId in user claims"}

{"error": "not authorized for business"}

Available Scopes

Best Practices

Key Security

• Store safely: Use environment variables or secrets management systems (AWS Secrets Manager, HashiCorp Vault, etc.)
• Never commit to version control: Add .env and similar files to .gitignore
• Rotate regularly: Create new keys and revoke old ones on a scheduled basis
• Prefer one key per business unless you need a multi-business key: Classic keys need no tenant header. Multi-business keys must send X-Business-ID on every /e9v3 call.
• Use separate keys per environment: Maintain distinct keys for development, staging, and production
• Revoke immediately if compromised: If a key is exposed, revoke it using the DELETE endpoint

Scope Management

• Principle of least privilege: Grant only the scopes your integration actually needs
• Review regularly: Audit your active keys and remove any that are no longer in use
• Set expiration dates: Consider setting expiration dates for time-limited integrations

Monitoring

• Monitor for errors: Alert on repeated 401/403 errors which may indicate compromised credentials
• Track usage: Monitor which keys are being used and from which IP addresses (if applicable)
• Audit logs: Keep records of when keys are created, rotated, and revoked