> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys for scripts and servers; sign-in connections for AI assistants; and which workspace each one uses.

Every request acts for one workspace. It spends that workspace's API credits and sees that workspace's saved research. How the workspace is chosen depends on how you connect.

| | API key | MCP connection |
| - | - | - |
| For | Scripts, servers, spreadsheets | AI assistants: Claude, ChatGPT, Cursor |
| Works on | REST (`https://api.alura.io/v1`) and MCP | MCP only (`https://mcp.alura.io/mcp`) |
| Workspaces | One, fixed when the key is created | All of yours, one current workspace at a time |
| Created by | A workspace owner or admin | You, when you sign in and approve |

## API keys

Create keys in [platform.alura.io](https://platform.alura.io/settings) under **Settings**, then **API keys**. Only workspace owners and admins can create, rotate and revoke them. Send the key as a bearer token:

```bash theme={null}
curl https://api.alura.io/v1/me \
  -H "Authorization: Bearer $ALURA_API_KEY"
```

`GET /v1/me` is free and tells you which user, workspace, plan and scopes the key carries.

What to know about keys:

* **A key is bound to one workspace.** It is chosen when the key is created and never changes. `POST /v1/me/workspace` with a key answers `403 workspace_locked`. To work in another workspace, create a key there.
* **A key acts as the person who created it.** It sees their private saved lists, and it stops working when they leave the workspace or are no longer an owner or admin.
* **Keys are server-side only.** Use them from your servers and scripts, never in a browser or a web page, and never paste them into a website, these docs included: the API reference shows examples and sends no requests. A request that sends a key from a browser is refused with `403 browser_refused`. A key in a URL is refused too, because URLs end up in logs; rotate one that was put there.
* **Rotating** gives you a new key with the same name and scopes. The new key acts as you, the person who rotated it. The old one keeps working for 24 hours, so you can deploy the new one first. A key can be rotated once.
* **Revoking** stops a key within a second.
* A workspace can have at most 25 active keys.

Keys start with `alura_sk_` and end with a checksum, so a secret scanner can spot one committed by mistake.

## MCP connections

AI assistants connect with OAuth: you sign in with your normal Alura account, see what the assistant asks for, and approve it. There is no key to copy. [Connect an AI assistant](/connect-ai) has the steps for each client.

A connection covers every workspace you are a member of, with **one current workspace** at a time:

* When you approve the connection, the current workspace is your active workspace in the app. If you are in more than one workspace, the approval screen lets you pick another.
* Every call the assistant makes uses the current workspace. Switching workspaces in the Alura app does not change it.
* If you are in more than one workspace, the assistant also gets two free tools: `list_workspaces` shows your workspaces with the current one marked, and `switch_workspace` changes it. The change applies to the next call, and to every conversation that uses the same connection. Users in a single workspace don't see these tools.
* The first time a connection switches into a workspace, Alura emails that workspace's owners.
* If you are removed from the current workspace, calls answer `403 workspace_required` until the assistant switches to another one.

Over REST with an API key, `GET /v1/me/workspaces` lists the key's one workspace, and `POST /v1/me/workspace` answers `403 workspace_locked`.

OAuth access tokens work only on the MCP endpoint. REST takes API keys.

## Scopes

| Scope | Allows |
| - | - |
| `research:read` | Products, shops, keywords, categories |
| `saved:read` | Reading saved folders, lists and items |
| `saved:write` | Creating, changing and deleting saved research |
| `usage:read` | `GET /v1/usage` and the usage history |

A call without the scope it needs answers `403 insufficient_scope`. AI assistants only see the tools their connection's scopes allow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.