Authentication and scopes
Authenticate to the Lookio API with an API key or an OAuth token, and choose the scopes that decide what a credential may do.
Send a credential in the Authorization header of every request.
curl https://api.lookio.app/v1/account \
-H "Authorization: Bearer $LOOKIO_API_KEY"A key looks like sk_live_<id>_<secret>_<checksum>. Never put it in a URL or in front-end code. The API sends no CORS headers on /v1, so a browser cannot call it.
Two kinds of credential
| API key | OAuth connection | |
|---|---|---|
| Created by | An admin, in Developer tools. | A person, who approves it in the app. Used by the CLI login and by MCP clients. |
| Belongs to | The workspace. | The person who approved it. |
| Permissions | Its scopes, and optionally a list of assistants. | Its scopes, narrowed by the person’s own Lookio permissions at every call. |
| Conversations | Keeps the conversations it starts. Continue them with conversation_id. Name your users with end_user, or send store: false to keep nothing. | Keeps the person’s own chats. Continue them with conversation_id. |
| Members and tags | Never. | Admins only, with the admin scope. |
| Lifetime | Until it expires or is revoked. | Access token 30 days, renewed by a refresh token valid 90 days. |
Use an API key for a job or a backend. Use a connection for a person’s CLI or AI client. See API keys.
Scopes
A scope is a permission on a credential. If the credential does not have the scope of an endpoint, the request fails with insufficient_scope. Each endpoint page names its scope.
| Scope | Lets the credential |
|---|---|
account:read | See your workspace, plan, and credit balance. |
usage:read | See credit usage over time, and the answer log: when, which assistant, which channel, what it cost. Not the questions. |
resources:read | See resources, their indexed text, their status, the pages of a site, and the indexing log. |
resources:write | Add, edit and re-index resources, and sync sites. Free of credits. |
resources:delete | Delete resources and their indexed passages. |
assistants:read | See assistants and their settings. |
assistants:write | Create and edit assistants and widgets, choose what they read, and read their conversations in the logs. |
assistants:delete | Delete assistants and widgets. Their resources stay. |
query | Ask questions, at the mode’s price, and search passages, at 1 credit. Rename and delete conversations, and send thumbs. |
admin | Manage members’ permissions and assistants, and read the activity log. Admins only. |
webhooks:write | Manage the webhooks that tell your systems when an import ends. Not available yet: no endpoint uses it. |
query is the only scope that spends credits. Deleting has its own scopes, so a key can create and edit without the right to delete. Widgets use the assistant scopes.
GET /v1/account (MCP: get_account) returns credential.scope_descriptions. It gives one sentence for each scope of the credential.
What a credential can really do
GET /v1/account returns the scopes that a credential can really use. They are its granted scopes, minus:
- for a connection, what the admin does not let members give to AI clients;
- for a connection, what the person’s own permissions refuse, checked at each call;
- for an API key,
admin. A key never manages people.
On the Pro and Custom plans, a person also needs the api permission for the REST API and the CLI, and mcp for an MCP client. If not, the call fails with permission_denied.
OAuth
An MCP client or the CLI gets a token through OAuth 2.1. You do not need this to use an API key.
- Authorization code with PKCE. PKCE with
S256is required.plainis refused. - Device code (RFC 8628) for machines without a browser. Poll every 5 seconds. The code is valid for 15 minutes.
- Refresh tokens renew access tokens.
- Client registration by Client ID Metadata Document (an
httpsclient id) or by dynamic registration (RFC 7591). All clients are public: there is no client secret.
The endpoints are at /.well-known/oauth-authorization-server, on api.lookio.app and on mcp.lookio.app.
| Endpoint | Path |
|---|---|
| Authorization | /authorize |
| Token | /oauth/token |
| Device authorization | /oauth/device |
| Registration | /oauth/register |
| Revocation | /oauth/revoke |
You can request a token for one resource (RFC 8707): https://api.lookio.app/v1, https://mcp.lookio.app/mcp or https://mcp.lookio.app/mcp/code. Such a token works only there. A token without resource works everywhere.
See Connect an AI client for the MCP flow.
Failures
| Code | Meaning |
|---|---|
authentication_required | No Authorization: Bearer header. |
invalid_api_key | The credential is malformed or unknown. |
api_key_expired | The credential passed its expiry. |
api_key_revoked | An admin revoked it, or the person behind a connection left the workspace. |
insufficient_scope | Valid credential, missing scope. |
permission_denied | The person does not have a Lookio permission. |
Lookio limits repeated failed sign-ins from one address. See Rate limits.