# API authentication

> Create a Botyard API key with an owner, member or viewer role, and use it to authenticate requests to the REST API for one organization.

Canonical URL: https://docs.botyard.io/docs/api/authentication

The Botyard API uses **API keys** for authentication. Each key belongs to a single
organization and has a **role**: owner, member or viewer. You choose the role when you
create the key, and it decides what the key can do in that organization.

> [!NOTE]
> The API surface is in preview. The header name and key format are subject to change before
> general availability. Watch the [release notes](/release-notes) for breaking changes.

## Creating an API key

1. Sign in to [app.botyard.io](https://app.botyard.io).
2. Open **User menu** › **Settings** › **General** › **API Keys**.
3. Click **Create Key**.
4. Enter a name. The name is for your reference only.
5. Choose a **Role** for the key. New keys default to **member**.
6. Click **Create Key**, then copy the key.

You need the owner role in the organization to create, list or revoke API keys.

API keys are shown **once** at creation time. Store them in a secrets manager. Botyard does
not retain a recoverable copy.

### Choosing a role

Give each key the lowest role that covers its job:

| Role       | What the key can do                                                                                                                                                                                   |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **viewer** | Read most organization resources, except the audit log and single sign-on settings. A viewer key is read-only apart from a few small actions, such as submitting a message to the organization inbox. |
| **member** | Everything a viewer can do, plus everyday work: create workforce boards and work on tasks, start conversations and send messages, and manage skills.                                                  |
| **owner**  | Full organization administration: create bots, and manage provider credentials, MCP servers, Runtime Vault secrets, members, billing and API keys.                                                    |

Use a viewer key for read-only automation such as reporting. Use an owner key only for tools that
manage organization configuration, such as [Terraform](/docs/terraform).

A key keeps the role it was created with, even if the role of the person who created it changes
later. A key can't be given a higher role than the person who creates it.

## Using an API key

Pass the key in the `Authorization` header as a bearer token:

```bash
curl https://api.botyard.io/v1/me/orgs \
  -H "Authorization: Bearer $BOTYARD_API_KEY"
```

This request works with a key of any role. It returns the key's organization, including its
`org_id` (which most endpoints take in their path) and the key's `role_id`.

Every authenticated request must include this header. A request with a missing, malformed or
revoked key returns `401 Unauthorized`. A request the key's role doesn't allow returns
`403 Forbidden`.

To try a key without writing any code, paste it into the **Authentication** panel of the
[interactive API console](/api-docs) and send a request from the browser. The key is kept in
memory for that tab only — it is not stored, and requests go straight to `api.botyard.io`.

## Rotating keys

Treat API keys like passwords. To rotate:

1. Create a new key in the dashboard.
2. Update your clients to use the new key.
3. Revoke the old key from **User menu** › **Settings** › **General** › **API Keys**.

There is currently no scheduled rotation or expiry. Keys remain valid until revoked. When a
person is removed from the organization, every key they created there is revoked
automatically.

A bot created with an API key is owned by that key. No other API key can change or delete the
bot, including its skills, tools and credentials, even an owner key. The creating key can add
people as owners of the bot, and those people can manage it too.

Once the creating key is revoked, an organization owner, or an owner key, can take over the bot,
but only if the bot has no other owner left. If a person was added as an owner of the bot, they
keep managing it, and other keys still get `403 Forbidden`. When you rotate a key that created
bots, revoke the old key before you use the new one to change them.

## Limitations (preview)

* **One organization per key.** Cross-org access requires separate keys.
* **Access is set by role.** A key has one of the three organization roles. You can't
  restrict a key to specific endpoints or resources.
* **Rate limits are not yet documented** and may change without notice during preview.