> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cedarai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API clients
> 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](/user-docs/api-reference/introduction). You can also create keys in the Admin Portal; see
[Tools and API keys](/user-docs/admin/tools-api-keys) for how the two compare.
## The API clients list
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.
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**).
## Create an API client
Select **Create API client**. The **Setup** panel on the right tracks the five steps.
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.
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.
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.
Check the summary, then select **Create client**.
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**.
Cedar can't show the key again after you leave this screen. If it's lost, rotate the credential to get a new one.
### Available API families
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.
## Call the API with your key
Send the key in the `x-arms-api-key` header and the email of one of the client's assumed users in the
`x-arms-assume-user` header.
```bash theme={null}
export CEDAR_API_KEY=""
curl -X POST "https://api-lg.arms.cedarai.com/ims/equipment/inventory?carrierId=" \
-H "x-arms-api-key: $CEDAR_API_KEY" \
-H "x-arms-assume-user: integration-bot@example.com" \
-H "Content-Type: application/json" \
--data '{"pageSize": 20}'
```
`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](/user-docs/api-reference/introduction#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](/user-docs/api-reference/introduction).
## Manage an API client
Select a client in the list to open its details.
### Change the endpoints
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.
### Manage assumed users
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 the credential
Rotate before a key expires, or whenever you need a new one.
Select **Rotate credential**. Choose the **Replacement expiry** and the **Overlap hours** (24 by default, up to 168).
Select **Create replacement**. The new key is shown once; save it the same way as before.
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.
### Revoke a credential
Under **Credentials**, select **Revoke** next to a key and confirm. The key stops working immediately. This can't be
undone.
### Delete the client
Select **Delete API client** and type the client's name to confirm. This revokes every key the client has and removes its
API access.
### Credential statuses
| Status | Meaning |
| - | - |
| **active** | The key works |
| **retiring** | A replacement exists; this key works until the overlap ends |
| **revoked** | The key was revoked and no longer works |
| **expired** | The key passed its expiry date |
Each key also shows when it was **Last used**, which helps you confirm an integration has switched to a new key.
### Client details
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**.
## When a client needs attention
* **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.
## Related pages
* [API documentation](/user-docs/api-reference/introduction)
* [Tools and API keys](/user-docs/admin/tools-api-keys)
* [Access and permissions](/user-docs/data-depot/access)
## Related topics
- [Tools & API Keys](/user-docs/admin/tools-api-keys.md)
- [API Introduction](/user-docs/api-reference/introduction.md)
- [Access and permissions](/user-docs/data-depot/access.md)
- [Use Cedar data in Databricks](/user-docs/data-depot/databricks.md)
- [Choosing the right option](/user-docs/data-depot/choosing.md)