Create expiring, carrier-scoped API keys that can call only the Cedar API endpoints you choose.
An API client is a named integration with its own API key. You decide which Cedar API endpoints it can call, which
Cedar users it may act as, and when its key expires. Use API clients for system-to-system integrations instead of
sharing a person’s login.
API clients issue keys for Cedar’s public APIs, the same APIs described in the
API documentation. You can also create keys in the Admin Portal; see
Tools and API keys for how the two compare.
Open API in the sidebar. The list shows every client for the selected carrier, with the API families it can call,
its current key (by its last characters) and expiry, and its status.
API clients for a carrier, with clients that need attention flagged
The need attention count at the top includes clients that:
show action required;
have No assumed users;
have an expired key, or one that expires within 14 days (shown as Expires in N days).
Select Create API client. The Setup panel on the right tracks the five steps.
1
Client details
Enter a Client name that says what the integration is for, such as “Nightly inventory export”. The Carrier is
the one selected in the sidebar; the key works only for that carrier. Choose a Credential expiry: the default is
90 days from today and the maximum is 365 days, unless your organization’s credential policy sets other limits.
Name the client and choose when its key expires
2
API access
Choose only the endpoints the integration needs. Endpoints are grouped by API family, and you can search by family
or endpoint name. Each endpoint shows its HTTP method, path, a short description, and a Documentation link. Use
the checkbox next to a family name to select every endpoint in it. The Selected access panel summarizes your
choice.
Select the endpoints the client may call
3
Assumed users
Every API call acts on behalf of a Cedar user, called the assumed user. Search for the users this client may act
as and select them. Alternatively, link a Source group to keep the list in sync with the members of one Cedar user
group.
Choose the Cedar users the client may act as
4
Review and create
Check the summary, then select Create client.
5
Save credential
The new key is shown once. Select Copy credential and store it in your secret manager. Tick I saved the
credential in an approved secret manager, then select Finish.
The key is shown once. It is cleared when you leave the page.
Cedar can’t show the key again after you leave this screen. If it’s lost, rotate the credential to get a new one.
Railcar, Waybill, Work Order, Bookings, Charges, Shipper Invoices, Shipper Quotes, Truck Load Tender, Network Structure,
and Notes. Which endpoints you can choose depends on Cedar’s published API catalog; an endpoint marked Deprecated is
being retired and shouldn’t be used for new integrations.
carrierId is your carrier’s numeric ID. Data Depot shows it as the foreign carrier ID on a Postgres source’s details
page, for example “Carrier-scoped to DEMO · Demo Rail Group (foreign carrier ID 9001)”.
The Starter request shown after you create a key sends the key in an Authorization: Bearer header. Cedar’s APIs
read the key from x-arms-api-key, so use the headers above. Don’t add a Bearer prefix to the key.
Use the right region. Keys are region-specific. Carriers in the EU use the cedarai.se hostnames instead of
cedarai.com. See Regions.
Permissions come from the assumed user. A call succeeds only if the endpoint is selected on the client and the
assumed user’s own Cedar roles allow it.
Find each endpoint’s URL and body from the Documentation link in Data Depot or the
API documentation.
Select Edit access, change the selected endpoints, and select Save changes. The bar at the bottom summarizes the
change, for example “Access will change from 4 to 6 endpoints”. The key doesn’t change.
The Assumed users section shows how many users can call the client’s APIs.
Under Direct members, select Add users or Remove next to a user.
Under Source group, select Link source group to sync membership from one Cedar user group. A linked group shows
Synced, or Sync pending while changes are applied. You can Replace or Unlink it.
If a client has no assumed users, it shows No assumed users. Its calls can’t act as anyone, so add at least one.
Rotate before a key expires, or whenever you need a new one.
1
Start the rotation
Select Rotate credential. Choose the Replacement expiry and the Overlap hours (24 by default, up to 168).
2
Save the new key
Select Create replacement. The new key is shown once; save it the same way as before.
3
Switch your integration
Both keys work during the overlap. Update your integration to the new key before the overlap ends. After that the old
key, shown as retiring, stops working automatically.
Rotate with an overlap so your integration never loses access
The Client details panel shows the carrier, when the client was created, and the API catalog version it was built
against. Data Depot manages a user group, role, and binding in the Admin Portal for each client; Technical details
links to them with Open in Admin.
Action required. A change didn’t finish applying. Select Retry cleanup and reconciliation to try again. This
needs the permission to delete API clients.
Credential delivery could not be confirmed. The connection dropped while a new key was being created. Select
Check request status. If the key can’t be shown, select Revoke unseen credential and generate replacement to get
a new one safely.
The API catalog changed. If Cedar retires an endpoint while you’re creating or editing a client, Data Depot asks
you to review the updated selection.
