# Stokis auth.md

How an AI agent or a script gets access to the Stokis API (https://stokis.io/api/v1).

## Who this is for

Agents and scripts that read a store's Stokis data on behalf of the store owner: products and stock, suppliers, purchase orders, daily sales and demand forecasts. The owner runs the Stokis workspace; the agent works for them.

## Getting a key

A person creates the key; an agent can't.

1. The workspace owner signs in at https://stokis.io/sign-in and opens Settings › Developers (https://stokis.io/settings?tab=developers).
2. Under Public API they choose New key, name it (for example "Inventory agent") and copy it. It starts with `sk_live_` and is shown only once.
3. The owner gives the key to the agent, for example as the environment variable `STOKIS_API_KEY`.

There is no registration or provisioning endpoint for agents, no OAuth authorization server and no client-credentials flow. Don't try to create accounts or keys through the API.

## Method

Bearer API key, sent in the Authorization header with every request:

```
Authorization: Bearer sk_live_…
```

Check that a key works:

```
curl "https://stokis.io/api/v1" \
  -H "Authorization: Bearer $STOKIS_API_KEY"
```

A working key gets 200 with the API version and its resources.

## Limits

- Read-only: GET requests only. A key can't change anything in Stokis or in the store.
- One workspace: a key reads only the workspace it was created in.
- Plan: the workspace must be on the Scale plan or in its 30-day trial. Otherwise every call answers 402.
- Rate limit: 30 requests a minute per IP address and URL path; over it, 429 with `retryAfter` in seconds.
- Revoking: only the owner creates and revokes keys, in Settings › Developers. A revoked key answers 401 at once. Keys don't expire by themselves.

## Errors

- 401 `auth_error`: the header is missing, or the key is malformed, unknown or revoked. Ask the owner for a new key.
- 402 `auth_error`: the workspace is not on Scale or in its trial. The owner has to upgrade; the key stays valid.

## More

- API reference: https://stokis.io/docs/api
- OpenAPI 3.1: https://stokis.io/docs/api/openapi.json
- API catalog (RFC 9727): https://stokis.io/.well-known/api-catalog
