> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/settings/workspace/api-clients.md).

# API Clients

## API Clients

API clients let external systems connect to your Flapjax workspace with secure tokens. Find them under **Settings → Access Clients**.

***

### What Are API Clients?

Each API client generates a **bearer token**, a unique credential your external applications use to authenticate API requests to Flapjax. Every token carries **permission scopes** that set exactly what the integration can reach.

Clients connect over two protocols:

* **HTTP**, the REST API described in the developer documentation.
* **RabbitMQ / AMQP**, a message-based protocol for streaming events into your workspace.

Pick the protocol that matches how your integration sends data.

***

### Viewing API Clients

The API clients list shows each client with its:

* **Name**, the label you gave it at creation
* **Scopes**, the permissions on this token, shown as coloured tags

The search bar finds a client by name.

***

### Creating an API Client

Click **Generate token** in the top-right corner, then fill in:

* **Name**, a descriptive name for this integration, such as "Website Integration" or "Mobile App". Names must be unique.
* **Scopes**, one or more permissions. At least one is required.

#### Available Scopes

Scope values are colon-separated, in the form `action:resource`.

| Scope             | Description                                              |
| ----------------- | -------------------------------------------------------- |
| **read:people**   | Read data, covering both contacts **and** stack records  |
| **write:people**  | Create, update and delete contacts, plus consent updates |
| **write:records** | Create, update and delete stack records                  |

{% hint style="info" %}
`read:people` grants read access to records too, so records need no separate read scope. The scopes `delete:people`, `read:records` and `delete:records` appear in the list and no endpoint requires them today.
{% endhint %}

Click **Save** to generate the token.

***

### Copying Your Token

The modal displays your generated token after you create the client. **Copy it immediately.** Flapjax shows it once and can never retrieve it for you.

{% hint style="warning" %}
**Warning:** store your token securely. Lose it and you must delete the client and create a new one.
{% endhint %}

***

### Token Lifetime and Rotation

**Tokens expire 30 days after creation.** The expiry is baked into the token at creation and cannot be extended.

An expired token gets every request rejected with a **401 Unauthorized**, before it reaches your data. No automatic renewal exists, so plan to rotate each token before it hits the 30-day mark.

#### Rotating a token

Flapjax has **no rotate endpoint** and no way to reissue a token for an existing client. Treat rotation as replace-and-retire:

1. **Create a new client** with the same scopes, as covered above, and copy its token.
2. **Update your integration** to use the new token.
3. **Delete the old client** once the new token proves itself.

Leave yourself a buffer before the 30-day expiry, so the migration never turns into an outage.

#### Changing scopes takes effect immediately

Scopes live outside the token. Flapjax checks them against the client's current settings on every request.

Edit a client's scopes and the change applies **immediately** to the existing token. No new token is needed for a scope change. Only the 30-day expiry forces a new token.

***

### Editing an API Client

Click a client in the list to update its name or scopes. Scope changes take effect immediately on the existing token, as covered above.

***

### Deleting an API Client

Open the actions menu next to a client and select **Delete**. Any external system using that token loses access to your workspace at once.