> ## Documentation Index
> Fetch the complete documentation index at: https://www.adorabl.info/llms.txt
> Use this file to discover all available pages before exploring further.

# API clients

> Issue, scope, rotate, and revoke the credentials an integration uses to read and write your organization's data through the adorabl API.

An **API client** is a set of credentials you hand to an integration — middleware, a connector, or a partner tool — so it can read and write customers, suppliers, items, and sales orders in your organization. Each client is tied to one organization and carries only the **scopes** you grant it.

For how an integrator uses these credentials, see the [Partner API](https://www.adorabl.info/technical-reference/partner-api.md) reference.

## Open API clients

**1. Navigate**

1. Open **Settings** → **Data & Admin**.
2. Under **Integrations**, click **API clients**.

The header shows how many clients are active out of the total issued.

## Issue a client

**1. Name the client**

Under **Issue a client**, enter a **Name** that identifies the integration — for example, `Shopify middleware` or `3PL connector`. Click **Issue**.

**2. Copy the credentials**

adorabl shows the **Client ID** and **Client secret** once, under **New client credentials**. Use the copy buttons and store both in your integration's secret manager.

> [!WARNING]
>
> The secret is not shown again and adorabl cannot recover it. If it is lost, rotate it.

**3. Assign scopes**

A new client starts with **customers:read** only. Expand the client's card and tick the scopes the integration needs. Changes save immediately.

## Scopes

| Resource | Read scope | Write scope |
| - | - | - |
| Customers | `customers:read` | `customers:write` |
| Suppliers | `suppliers:read` | `suppliers:write` |
| Items | `items:read` | `items:write` |
| Sales orders | `sales_orders:read` | `sales_orders:write` |

Grant the smallest set that does the job. A read scope allows listing and fetching records; a write scope also allows creating and updating them. Writes follow the same rules as the matching screen — a sales order can only be updated through the API while it is still a draft, for example.

## Rotate a secret

Click the **Rotate secret** icon on a client card when a secret may have leaked or when your rotation policy requires it. adorabl issues a new secret and shows it once under **New secret**. The client ID does not change. Update the integration with the new secret; the old one can no longer obtain tokens.

## Revoke a client

Click **Revoke** on a client card and confirm. Revoked clients cannot obtain new tokens and show a **Revoked** badge. Revoking is permanent — issue a new client if the integration should regain access later.

> [!NOTE]
>
> Rotating or revoking stops new tokens immediately. A token the integration already holds stays valid until it expires, which is at most one hour.

## Example: Trail Ridge Outfitters

Trail Ridge connects a wholesale ordering portal that creates draft sales orders and needs the current catalog.

1. The admin issues a client named `Wholesale portal` and stores the client ID and secret in the portal's configuration.
2. They expand the card and tick `items:read`, `customers:read`, and `sales_orders:write`. The portal cannot touch suppliers or edit items.
3. Six months later the portal provider reports a compromised server. The admin clicks **Rotate secret** and pastes the new secret into the portal. The old secret can no longer obtain tokens, and any token already issued expires within the hour.

## Related guides

> **[Partner API](https://www.adorabl.info/technical-reference/partner-api.md)**
>
> Authentication flow, endpoints, and conventions for integrators.

> **[Organization settings](https://www.adorabl.info/admin-and-settings/organization-settings.md)**
>
> Data & Admin setup hub.

> **[Audit log](https://www.adorabl.info/admin-and-settings/audit-log.md)**
>
> Who changed what across your organization.

> **[Connect Shopify](https://www.adorabl.info/commerce/shopify.md)**
>
> adorabl's built-in Shopify connection does not need an API client.

## Troubleshooting

> **The integration gets a 401 Unauthorized**
>
> The client ID or secret is wrong, or the client was revoked. Confirm the integration is using the most recent secret — rotating invalidates the previous one — and that the card still shows **Active**.

> **The integration gets a 403 Forbidden**
>
> The client lacks the scope for that call. Expand the client card and grant the matching read or write scope, then have the integration request a new token.

> **I cannot find the secret I was shown**
>
> Secrets are shown once. Rotate the secret and store the new value.

> **The page says to sign in with an active organization**
>
> API clients belong to an organization. Pick the organization in the sidebar switcher, then return to the page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.