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 API clients page lists 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 working key, shown as Credential expired or Credential revoked;
have No assumed users;
have a key that expires within 14 days, shown as Expires in N days.
Select Create API client. The Steps 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 key works
through the end of that day in your time zone. 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.
Select More under a description to read all of it, and Less to fold it again. 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. You can continue without any, and add them later from the client’s page, but the client’s calls need one.
Choose the Cedar users the client may act as
4
Review and create
Check the carrier, expiry, endpoints, and assumed users, then select Create API 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 Starter request is a curl command to try the key with. It sends the key in the x-arms-api-key header and
an assumed user in the x-arms-assume-user header, with CEDAR_ASSUME_USER set to the first assumed user you
picked and your carrier’s ID filled in. If it shows <endpoint-path>, replace that with an endpoint the client may
call. The command reads the key from $CEDAR_API_KEY, so the key itself is never part of it.
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. The Starter request shown with a new key has it filled in, for example
export CARRIER_ID="9001" for DEMO · Demo Rail Group.
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 (the new key works through the end of that day) 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
If every key has expired or been revoked, the client shows Credential expired (or Credential revoked) and its API
calls fail. The button then reads Issue new credential. There’s no old key to overlap with, so you choose only an
Expiry and select Issue credential. Save the new key and update your integration with it.
Under Credentials, select Revoke next to a key, then Revoke credential to confirm. The key stops working
immediately. This can’t be undone. If it’s the client’s only working key, Data Depot warns you that the client’s API
calls will fail until you issue a new one.
Select Delete API client, type the client’s name, and select Delete API client again to confirm. This revokes
every key the client has and removes its API access.
The Client details panel shows when the client was created. Open Technical details for the client ID and the
API catalog version the client was built against. Data Depot manages a user group, role, and binding in the Admin
Portal for each client; Technical details links to each of them.
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 expired — API calls are failing. The client has no working key. Select Issue new credential. See
Rotate the credential.
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.
