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

# Authentication

> API keys, scopes, expiry, rotation, and why a key never belongs in a browser.

Every request carries an API key in the `Authorization` header:

```bash theme={null}
curl https://api.indm.social/v1/workspace \
  -H "Authorization: Bearer indm_..."
```

A key belongs to **one workspace** and sees only that workspace: its accounts, its posts, its automations. An id from anywhere else reads as not found.

## Create a key

Open **Settings → API keys** in the inDM app and choose **Create key**. Any member of the workspace can create one. You choose three things:

| | |
| - | - |
| **Name** | So you can tell keys apart later, such as "Content calendar" or "Client reporting". |
| **Access** | **Read only** or **Full access**. See [scopes](#scopes). |
| **Expiry** | 30 days, 90 days (the default), 365 days, or no expiry. |

The secret is shown **once**, when you create it. inDM stores only a hash of it, so we can't show it to you again. If you lose it, revoke it and create another.

Keys start with `indm_`, which makes them easy to spot in logs and in code review. The settings page shows each key's first characters and its last four so you can match a key to the place it's used.

## Scopes

A key's scope decides which routes it can call. Each route's scope is listed on its reference page.

| Scope | Covers |
| - | - |
| `read` | Every `GET` route, plus [Validate an automation](https://docs.indm.social/api-reference/automations/validate-automation.md), which writes nothing. |
| `full` | Everything `read` covers, plus the writes: create and update automations, set them live or paused, and refresh content. |

A `read` key on a write route gets `403` [`insufficient_scope`](https://docs.indm.social/errors#insufficient_scope). Give each integration the smallest scope it needs: a reporting job only ever needs `read`.

## Keep keys on your server

**An API key is a password for your workspace.** A `full` key can set automations live on your Instagram account. Treat it that way:

* Call the API from your server, a scheduled job or a serverless function. The API sends no CORS headers, so a browser can't call it directly, and that is deliberate.
* Never put a key in front-end code, a mobile app, or anything you ship to someone else's device. Anything shipped can be read.
* Keep keys in environment variables or a secrets manager, never in a repository.
* Use one key per integration, so you can revoke one without touching the others.

If a key may have leaked, revoke it straight away. It stops working on the next request.

## Expiry and rotation

An expired key gets `401` [`api_key_expired`](https://docs.indm.social/errors#api_key_expired). To rotate without downtime:

**1. Create the new key**

Create a key with the same scope in **Settings → API keys**.

**2. Deploy it**

Put the new key wherever the old one is used, and confirm requests succeed with it. [Get the workspace](https://docs.indm.social/api-reference/workspace/get-workspace.md) returns the calling key's `expires_at`, which makes a good health check.

**3. Revoke the old key**

Revoke the old key in **Settings → API keys**. It stops working on its next request.

A workspace can hold up to 10 active keys at a time, which leaves room to rotate.

> [!WARNING]
>
> A key with no expiry keeps working until someone revokes it. Choose it only when the key lives somewhere you control and review.

## When a key stops working

| Code | What happened |
| - | - |
| [`api_key_missing`](https://docs.indm.social/errors#api_key_missing) | The request had no `Authorization: Bearer` header. |
| [`api_key_invalid`](https://docs.indm.social/errors#api_key_invalid) | The key isn't one inDM issued. Usually a copy that lost characters. |
| [`api_key_expired`](https://docs.indm.social/errors#api_key_expired) | The key passed its expiry date. |
| [`api_key_revoked`](https://docs.indm.social/errors#api_key_revoked) | Someone revoked it, or the person who created it left the workspace. |

Keys are revoked automatically when the member who created them leaves the workspace, so access always follows the team.


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