Skip to main content
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 keys

Create keys in platform.alura.io under Settings, then API keys. Only workspace owners and admins can create, rotate and revoke them. Send the key as a bearer token:
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 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

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