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

# Authentication

> Authenticate every request with a workspace API key sent as a Bearer token.

Every request is authenticated with an **API key** in the `Authorization` header:

```bash theme={null}
curl https://api.pineyard.ai/v1/agents \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Key format

API keys start with `pk_live_` followed by a random string (about 43 characters). Treat the whole value as a
secret: anyone who has it can act on your workspace within the key's scopes.

## Getting a key

API keys are **issued by Pineyard on request**. Contact your Pineyard account team with:

* the workspace the key is for,
* a name to recognise the key by (for example `Acme backend`),
* the [scopes](/concepts/scopes) your integration needs. Ask for the minimum.

<Warning>
  The secret is shown **once**, when the key is issued. Pineyard stores only a hash of it and cannot recover
  it later. If you lose a key, ask for a new one and have the old one revoked.
</Warning>

Store the key in your secrets manager or environment, never in client-side code, mobile apps or source control.

## What a key can do

* A key belongs to **one workspace** and only ever sees that workspace's data. See [Workspaces](/concepts/workspaces).
* A key has **scopes**: the same permissions your dashboard roles use, such as `campaigns.edit` or `calls.view`.
  See [Scopes & permissions](/concepts/scopes).
* A key **acts on behalf of a member of your workspace** (by default the workspace owner). It can do at most what
  that member can do right now: if their role is narrowed, the key is narrowed too; if they are removed or
  suspended, the key stops working (`403 api_key_owner_inactive`).
* Some actions need a person and are never available to keys, whatever their scopes: signing in to third-party
  services, payments and wallet top-ups, identity verification, and personal settings and notifications.
  These return `403 api_key_not_allowed`.

## Rotating and revoking

To rotate a key, ask Pineyard for a new key with the same scopes, switch your integration over, then have the old
key revoked. A revoked key fails with `401 invalid_api_key` on its next request. Workspace admins can also revoke
keys from the Developers page in the dashboard.

A key can also be issued with an expiry date; after it, requests fail with `401 invalid_api_key`.

## Authentication errors

| Status | `error` | Meaning |
| - | - | - |
| 401 | `unauthorized` | No `Authorization: Bearer …` header, or an empty token. |
| 401 | `invalid_api_key` | The key is unknown, revoked or expired, or its workspace was deleted. |
| 403 | `api_key_not_scoped` | A key issued without scopes was used outside `/v1`. Ask Pineyard to add scopes to it. |
| 403 | `api_key_owner_inactive` | The member the key acts for was removed or suspended. |
| 403 | `workspace_suspended` | Your workspace is suspended. |
| 403 | `workspace_pending_approval` | Your workspace has not been approved yet. |

See [Errors](/concepts/errors) for every error code.


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