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:

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 your integration needs. Ask for the minimum.

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.

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.
• A key has scopes: the same permissions your dashboard roles use, such as campaigns.edit or calls.view. See Scopes & permissions.
• 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 for every error code.