Authentication

Every request outside the device-flow endpoints needs a bearer credential. Send it in the Authorization header:

curl https://api.estii.com/v1/spaces \
  -H "Authorization: Bearer estp_your_token"

The estii CLI reads the same token from the ESTII_TOKEN environment variable, or you can run estii auth login for the interactive device flow.

Verify your token

GET /v1/spaces lists the spaces your credential can reach, so it doubles as a quick check that a token works. A valid token returns 200 with the list:

curl https://api.estii.com/v1/spaces \
  -H "Authorization: Bearer estp_your_token"

{
  "items": [
    {
      "id": "sp_abc",
      "name": "Acme",
      "role": "owner",
      "is_member": true,
      "plan": "pro",
      "updated_at": 1738368000000
    }
  ],
  "next_cursor": null
}

A missing or invalid token returns 401 instead:

{ "message": "invalid or expired token" }

You can also call GET /v1/meta without a credential to read the current contract version before you build against it.

Credential types

There are two kinds of credential:

• Personal access tokens (estp_) act as a user across the spaces that user can reach. Create them in Account settings. Best for the CLI and personal scripts.
• Space API keys (ests_) act as a single space and keep working after the person who created them leaves. Create them in Space settings → API keys (owners and admins). Best for durable server-to-server integrations.

Scopes

Each credential carries a scope: read (read-only) or read_write (read plus mutating calls). A read credential is rejected on any mutating endpoint with a 403 and the message token scope does not permit writes.

Rate limits

Each credential is limited to 120 requests per 60-second window across the whole /v1 surface, expensive exports included. When you exceed it the API responds with 429 and a Retry-After header giving the seconds to wait before the window resets. Back off for that long, then retry.

Errors

Errors return the matching HTTP status with a JSON body:

{ "message": "bearer token required" }