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.

Creating an API key

1. Sign in to 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:

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.

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:

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 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.