Authentication

Every request to https://api.resia.ai uses a bearer token in the Authorization header:

Authorization: Bearer YOUR_RESIA_API_KEY

Resia accepts two kinds of bearer token:

Token Who uses it How to get it
API key Your software Create it in the portal under API Keys. See Get access.
Portal sign-in token A person signed in to the Resia portal with Google, GitHub, or an emailed sign-in link The portal handles it for you.

What an API key can do

Each API key has one scope. You choose it when you create the key, in the portal or with the scope field of Issue an API credential. The scope cannot change later. Each scope includes everything that the scope above it in this table can do:

Scope What the key can do HTTP methods
reader Read everything: agents, calls, recordings, transcripts, chats, texts, runs, tools, phone numbers, databases, 10DLC, billing, rate limits, and request logs. Also send feedback. GET, and POST /v1/feedback
editor Also create, change, and start work: create or edit agents, tools, and databases; place calls; send texts; start chats and runs; cancel batches, chats, and runs; buy phone numbers; register for 10DLC; top up and change billing settings. POST, PUT, PATCH
owner Also delete: archive agents and tools, and release phone numbers. DELETE

A new key is an editor key unless you choose another scope. A key that existed before scopes is an owner key.

A key without the scope for an action gets 403. The error code is forbidden; agent, tool, database, chat, and run routes write it as FORBIDDEN, in the same body shape as their other errors. The message names the key's scope and the scope that the action needs. Resia does nothing for that request, so nothing is saved, charged, or deleted.

Give each key the lowest scope that its software needs. For example, give a reporting job a reader key.

Some actions need a person who is signed in. An API key gets 403 on them:

  • Create or rename your organization.
  • Invite, list, or remove members.
  • Create, list, or revoke API keys.
  • Accept an invitation.

This keeps a leaked key from creating more keys or adding people to your organization.

Keep keys safe

  • Store keys in a secret manager, not in source code.
  • Use a key only on your server. Never send it to a browser or a mobile app.
  • Create one key per service, and give each a clear name, so that you can revoke one without affecting the others.
  • Resia shows each key once and stores only a fingerprint. If you lose a key, create a new one.
  • Revocation is immediate and permanent.

Endpoints that need no token

  • GET /health
  • The API contract and docs: /openapi.json, /changelog, and /llms.txt

Errors

A missing or bad token gets 401. A valid token without the right to do the action gets 403. A record that belongs to another organization gets 404. See Errors.