Skip to main content
The ARMS external API supports HTTP/2 and HTTP/1.1. All endpoints use HTTP POST.

​
Regions

Cedar’s production APIs run in two regions: US (primary, cedarai.com) and EU (cedarai.se). Same paths, same headers, same key shape — only the hostname suffix changes. Every other production hostname follows the same .com ↔ .se mapping — just swap the TLD.
API keys are region-scoped. A key issued for the US region won’t authenticate against an EU host (and vice versa). Use whichever region your account was provisioned in.
The per-endpoint reference pages expose a server dropdown above each “Try it” cURL snippet so you can flip between US and EU without editing the URL by hand. The base-URL blocks throughout this page are also shown as tabs for the same reason.
Staging and dev environments are US-only (.com) — there is no .se mirror for -staging or -dev hosts.

​
Authentication

Include the following headers on every request: Cedar’s IAM model makes API keys flow permissions through a user group, not directly through individual users:
1

An API key is bound to one or more user groups

When the key was created, your admin attached it to one or more user groups (for example, prod-integrations). The key can only act as users that are members of those exact same groups.
2

The assumed user must belong to one of those bound groups

Whatever email you put in x-arms-assume-user must be a current member of at least one of the user groups bound to the API key. If the user exists but isn’t in a bound group, the request is rejected with 401.
3

Permissions come from the assumed user, not the key

The effective permissions for the request are the union of all roles assigned to the assumed user (via their group memberships and/or direct bindings). A valid key + valid user with no permissions on the target endpoint returns 403, not 401.

​
Choosing what to pass in x-arms-assume-user

You have two reasonable approaches, and they trade off operational simplicity against audit-trail fidelity. Pick based on whether your integration needs to attribute every action to the real human in your other system.
Use one dedicated service-account user for all calls from a given integration (e.g. integrations@yourco.example).
Use SCIM to make Option B sustainable. SCIM provisions users and group memberships into Cedar from your IdP (Okta, Azure AD, etc.) automatically — every joiner, mover, and leaver in your directory is reflected in Cedar without manual Admin Portal work. Bind your API key to a group that’s managed by SCIM (e.g. cedar-api-users), and your IdP becomes the single source of truth for who can call the API as themselves. New hires get access automatically; departing employees lose it the moment they’re deactivated upstream — no orphan service accounts, no out-of-band reviews.
Many customers run both patterns in parallel: a service-account user for system-to-system jobs, and SCIM-managed pass-through for human-driven flows in their custom apps. Bind the API key to two groups (one per pattern), assign the same API access role(s) to both, and let your client decide which email to send per request.
Need an API key? API key management is coming soon to the Admin Portal. Contact your account representative for access.

​
AI agents (MCP)

Coding agents (Cursor, Claude Desktop, and other MCP clients) can call the same public ARMS APIs documented here through Cedar’s Model Context Protocol endpoint at https://mcp.arms.cedarai.com/mcp. Sign in with your Cedar account via OAuth — there is no separate MCP API key. Carrier admins choose which catalog operations each user may invoke by creating MCP access configs in Cedar Data Depot (open the MCP tab after selecting a carrier). Add users as members of a config; if a user belongs to more than one config, their agent sees the union of allowed operations.
MCP access management requires Data Depot permissions. If you do not see the MCP tab, ask your Cedar account team to grant MCP manager access for your carrier.

​
Troubleshooting 401 Unauthorized

A 401 means Cedar couldn’t authenticate the request — the key, the assumed user, or the link between them is wrong. Run through this checklist:

API key issues

  • Key is expired or rotated. Ask your admin to confirm the key is still active in the Admin Portal. Rotated keys stop working immediately.
  • Wrong header name. Cedar expects x-arms-api-key (lowercase). Some HTTP clients normalize header casing — verify the wire format if you’re behind a proxy.
  • Header value contains whitespace or quotes. The key value should be raw, no Bearer prefix and no surrounding quotes.
  • Key was bound to a different environment. Production keys won’t work against staging URLs and vice versa.
  • User doesn’t exist. The email in x-arms-assume-user must match a real, active Cedar user for your carrier.
  • User is deactivated. Deactivated users fail auth even if the key is valid. Reactivate the user in the Admin Portal.
  • Email casing or typo. The lookup is case-sensitive in some flows — confirm the exact spelling against the user’s profile.
  • Wrong header name. Must be x-arms-assume-user (lowercase, with the dash before user, not userid).
  • The assumed user isn’t in any group bound to the key. This is the single most common cause. Confirm in the Admin Portal that the user belongs to at least one user group that the API key is also bound to.
  • The user group lost its API-key binding. Group bindings can be removed independently of the key itself. Re-attach the key to the right group.
  • The user was removed from the group. Adding the user back to the bound group fixes auth immediately — no key rotation required.
  • Group has no roles. A user that’s in the right group but has no roles assigned will pass auth (avoid 401) but every endpoint will return 403. If you’re seeing 401, the linkage itself is missing.
  • Real-user pass-through with stale group membership. If you’re using Option B (real users), confirm your IdP push reached Cedar — the user may exist but not yet be in the bound group. SCIM usually syncs within a minute; a manual re-push from your IdP is the fastest fix for one-off cases.
  • Wrong carrier scope. API keys are scoped to one carrier. Calling against another carrier’s data — for example, by passing a carrierId query parameter from a different carrier — fails auth.
  • Cross-environment or cross-region call. Confirm the base URL matches both the environment and the region the key was issued in. Production ARMS uses api-lg.arms.cedarai.com (US) / .se (EU); production Notes uses api.linda.cedarai.com (US) / .se (EU); staging/dev use the -staging / -dev variants and are US-only. See Regions for the full mapping. Keys are region-scoped — a US key against an EU host (or vice versa) returns 401.
  • Clock skew. If you sign or timestamp the request out of band, large clock drift can look like 401 from intermediate proxies. Sync your client clock.
Capture the request id from the failing response (look for the x-arms-request-id header) and email support@cedarai.com with:
  • The full failing endpoint and HTTP method.
  • The masked x-arms-api-key (first 4 characters only) and the x-arms-assume-user email.
  • The response status, headers, and body.
  • The x-arms-request-id so support can trace the request end-to-end in our logs.

​
API access roles

Cedar ships a predefined system role per API section so you can grant a service account the exact permissions it needs without composing custom roles. Assign one (or more) of these to the user that your API key calls as via x-arms-assume-user.
Each section role grants only what’s needed to call the endpoints in that section. You can combine multiple roles on one user — for example, a finance integration that exports charges and reads invoices would get arms.chargeApi + shipping.invoiceApi. For pricing-tier roles (cedar.apiBasic, cedar.apiEssential, cedar.apiProfessional), see the API pricing page.

​
REST endpoints

​
Base URL for REST endpoints

​
Railcar API Endpoints

A high-level list of available endpoints:

​
Waybill API Endpoints

A high-level list of available endpoints:
Shipments that cross the US–Mexico border have additional required fields beyond the base schema. See Cross-border (Mexico) waybills before calling /ims/waybills/bill-of-lading for a MX origin or destination.

​
gRPC transcoded endpoints

These endpoints are sent to Envoy over HTTP and get proxied to a gRPC service.

​
Base URL for gRPC transcoded endpoints

If your service supports HTTP/2, use the following base URL:
If your service does not support HTTP/2, use the following base URL:

​
Work Order API

A high-level list of available endpoints:

​
Network Structure API

A high-level list of available endpoints:

​
Notes API

Threaded notes on shipments, equipment, waybills, work orders, invoices, and other records. See the Notes user guide for the in-app experience these endpoints power.
The Notes API is served by Cedar’s Linda service on its own dedicated host — not the ARMS gateway base URL above. Use the base URL below for all /v1/notes/* endpoints; calls to api-lg.arms.cedarai.com/v1/notes/... will not resolve.

​
Base URL for Notes API

​
View OpenAPI Specs

Use the links to view and save the OpenAPI specs in JSON format.

Work Order API

JSON spec

Network Structure API

JSON spec

Shipper Invoices API

JSON spec

Shipper Quotes API

JSON spec

Notes API

JSON spec

REST API

JSON spec

Admin Portal

Manage users, groups, roles, and access

IAM Concepts

Understand identity and access management

SSO Setup

Configure single sign-on

SCIM Provisioning

Automate user provisioning

API Pricing

API pricing calculator

Glossary

Key terms explained

Related topics

IntroductionGlossaryTools & API KeysComplete class list tasksAI summary of a note thread