Skip to main content

​
Overview

The Arcus API uses Bearer token authentication. Every request must include: Authorization: Bearer <api_key> — your API key The key itself carries your entity, so you do not send an entity ID on most requests. Resource routes are flat, for example GET https://api.arcuserp.com/v1/accounts to list accounts and POST https://api.arcuserp.com/v1/accounts to create one. A small set of platform endpoints (migration, reconciliation and a few others) take the entity in the path as /v1/entities/{entity_id}/...; on those, the entity ID must be the one the key was issued for. A request with a missing, malformed, unknown, or expired key returns 401 with code: invalid_api_key. A key that was revoked returns 401 with code: api_key_revoked. A key used on an /v1/entities/{entity_id}/... path for a different entity returns 403 with code: entity_isolation_violation.

​
API key types

​
Per-entity keys

Per-entity keys are the only key type available. They are issued to a specific entity and can only read or write data for that entity.
  • Created in Settings > Developers > API Keys
  • Scoped to a single entity (your tenant)
  • Format: ark_live_ent_<code>_<random> (production) or ark_test_ent_<code>_<random> (test mode)
  • Carry explicit scopes (e.g. orders:read, products:write)
The entity is identified by the key, not by a header. Most resources are addressed directly under the base URL:

​
Scopes

Every API key carries one or more scopes that control what the key can do. Scopes follow the pattern <resource>:<permission>. Requesting a resource you do not have scope for returns 403 Forbidden with code: insufficient_scope and a required field naming the missing scope. Some operations need more than one scope. For example, charging a payment against an order needs both orders:write and payments:write, and fulfilling an order automatically needs both orders:write and fulfillment:write. Each operation in the API Reference names the scopes it requires.

​
Scopes for accounts

​
Making an authenticated request

​
Test mode vs live mode

Test mode keys (ark_test_ent_...) and live mode keys (ark_live_ent_...) hit the same API base URL but are validated separately. A test-mode key cannot access live data and vice versa. Use test mode for development and integration testing. Use live mode only for production traffic.

​
IP allowlists

You can restrict an API key to a list of IP addresses or CIDR ranges with the IP allowlist field (one entry per line) when you create the key in Settings > Developers > API Keys. A key with no allowlist accepts requests from any address. Requests from unlisted addresses return 403 Forbidden with code: ip_not_allowed and the hint “Source IP is not in the API key allowlist.”

​
Key rotation

  1. Open the key in Settings > Developers > API Keys and choose Rotate key. Arcus creates a new key with the same name, scopes, mode, rate limit, and IP allowlist, and shows the new key once.
  2. Update your integration to use the new key
  3. Verify production traffic is using the new key (check your server logs)
Rotating revokes the old key at once, so its next request returns 401 with code: api_key_revoked and your integration must switch to the new key straight away. Plan the switch before you rotate, because there is no overlap window. Revoke key retires a key without issuing a replacement: revoking is permanent and immediate, and any request made with the key afterward returns the same 401 with code: api_key_revoked.

​
Security best practices

  • Store API keys in environment variables or a secrets manager, never in source code
  • Use the minimum scope required for each integration
  • Enable IP allowlists for production server-to-server integrations
  • Rotate keys every 90 days or immediately after any suspected exposure
  • Use separate keys for each integration so you can revoke one without impacting others