Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Arcus API uses Bearer token authentication. Every request must include:
  1. Authorization: Bearer <api_key> — your API key
  2. The entity ID as part of the URL path: /v1/entities/{entity_id}/{resource}
A request missing the Authorization header returns 401 Unauthorized. Requests to an entity the key is not scoped to return 403 Forbidden.

​
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 ID is part of the URL path, not a separate header: 
https://api.arcuserp.com/v1/entities/{entity_id}/{resource}

​
Scopes

Every API key carries one or more scopes that control what the key can do. Scopes follow the pattern <resource>:<permission>.
ScopeDescription
accounts:readList and retrieve accounts
accounts:writeCreate, update, and delete accounts
orders:readList and retrieve orders, quotes, and invoices
orders:writeCreate, update, confirm, cancel, and void orders
products:readList and retrieve products and variants
products:writeCreate, update, and delete products
inventory:readRead inventory balances and transactions
inventory:writeAdjust inventory, receive purchase orders
fulfillment:readRead packages and shipments
fulfillment:writeCreate packages, purchase labels, mark shipped
returns:readRead return authorizations
returns:writeCreate and process returns
purchasing:readRead purchase orders and vendor bills
purchasing:writeCreate and manage purchase orders
payments:readRead payment records
payments:writeRecord and process payments
accounting:readRead journal entries and GL accounts
accounting:writePost journal entries
integrations:readRead connector configuration
integrations:writeUpdate connector configuration
webhooks:readList webhook subscriptions
webhooks:writeCreate, update, and delete webhook subscriptions
Requesting a resource you do not have scope for returns 403 Forbidden with code: insufficient_scope and a required field naming the missing scope.

​
Making an authenticated request

curl https://api.arcuserp.com/v1/entities/{entity_id}/accounts \
  -H "Authorization: Bearer ark_live_ent_acme_..."

​
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 in Settings > Developers > API Keys > Edit. Requests from unlisted IPs return 403 Forbidden with code: ip_not_allowlisted.

​
Key rotation

  1. Create a new key in Settings > Developers > API Keys
  2. Update your integration to use the new key
  3. Verify production traffic is using the new key (check your server logs)
  4. Delete the old key
Old keys continue working until deleted; rotation is zero-downtime.

​
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