Authentication & scopes

API keys

Requests are authenticated with an API key sent as a bearer token:

Authorization: Bearer stoneity_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Keys are created by workspace administrators under Settings → Apps → API keys.
• The key identifies the workspace; there is no tenant header.
• Keys can be rotated (a new key replaces the old one immediately, same service account) and revoked (the service account is deactivated).
• Keys may carry an optional expiry date. An expired key returns 401 with code api_key_expired.

Store keys in a secret manager. If a key leaks, rotate it from the settings page.

Service accounts

Each key acts as a service account user with the role chosen at creation time. Everything the key does is recorded under that account's name. The account cannot sign in to the UI and does not count towards your seat limit. The role's board access rules apply to the key exactly as they would to a person.

Scopes

A key can only call operations covered by its scopes:

Scope	Allows
tickets:read	List/get tickets, comments and attachments
tickets:write	Create/update tickets, change state and assignee, add comments and attachments
boards:read	Boards, fields, option lists and states
users:read	Users, requesters and companies
users:write	Invite users/requesters, create companies
kb:read	Published knowledge base articles
webhooks:manage	Webhook subscriptions and delivery logs

A call without the required scope returns 403:

{ "errors": [ { "code": "insufficient_scope", "message": "This operation requires the `tickets:write` scope." } ] }

Environments

Every key starts with stoneity_ and carries no environment marker. A key belongs to the workspace it was created in and works only there, so the same key format is used on production and on test.