Authentication

Overview

The Arcus API uses Bearer token authentication. Every request must include:

Authorization: Bearer <api_key> — your API key
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>.

Scope	Description
`accounts:read`	List and retrieve accounts
`accounts:write`	Create, update, and delete accounts
`orders:read`	List and retrieve orders, quotes, and invoices
`orders:write`	Create, update, confirm, cancel, and void orders
`products:read`	List and retrieve products and variants
`products:write`	Create, update, and delete products
`inventory:read`	Read inventory balances and transactions
`inventory:write`	Adjust inventory, receive purchase orders
`fulfillment:read`	Read packages and shipments
`fulfillment:write`	Create packages, purchase labels, mark shipped
`returns:read`	Read return authorizations
`returns:write`	Create and process returns
`purchasing:read`	Read purchase orders and vendor bills
`purchasing:write`	Create and manage purchase orders
`payments:read`	Read payment records
`payments:write`	Record and process payments
`accounting:read`	Read journal entries and GL accounts
`accounting:write`	Post journal entries
`integrations:read`	Read connector configuration
`integrations:write`	Update connector configuration
`webhooks:read`	List webhook subscriptions
`webhooks:write`	Create, 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_..."

import Arcus from '@arcuserp/sdk-node';

const arcus = new Arcus({
  apiKey: process.env.ARCUS_API_KEY,
  entityId: process.env.ARCUS_ENTITY_ID,
  // baseUrl: 'https://api.arcuserp.com/v1', // optional; defaults to the Arcus API base URL
});

from arcuserp import Arcus
import os

arcus = Arcus(
    api_key=os.environ['ARCUS_API_KEY'],
    entity_id=os.environ['ARCUS_ENTITY_ID'],
)

import (
    arcus "go.arcuserp.com/sdk"
    "os"
)

client := arcus.NewClient(
    os.Getenv("ARCUS_API_KEY"),
    arcus.WithEntityID(os.Getenv("ARCUS_ENTITY_ID")),
)

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

Create a new key in Settings > Developers > API Keys
Update your integration to use the new key
Verify production traffic is using the new key (check your server logs)
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

Get Started

Concepts

Guides

SDKs

Collections

Overview

API key types

Per-entity keys

Scopes

Making an authenticated request

Test mode vs live mode

IP allowlists

Key rotation

Security best practices

​Overview

​API key types

​Per-entity keys

​Scopes

​Making an authenticated request

​Test mode vs live mode

​IP allowlists

​Key rotation

​Security best practices

Overview

API key types

Per-entity keys

Scopes

Making an authenticated request

Test mode vs live mode

IP allowlists

Key rotation

Security best practices