# Authentication

Two ways in: sign in from an AI app, or send an API key. Both are for owners and admins.

Every request to the endpoint carries a credential in the `Authorization` header. There are two kinds. Both act for the person who created them, inside one workspace, within the [scopes](https://soontra.com/docs/scopes) they chose.

|  | Sign-in (OAuth) | API key |
| --- | --- | --- |
| Made for | Chat apps: ChatGPT, Claude, Gemini, Grok, Perplexity | Editors, command-line tools and your own code |
| How it starts | The app sends you to Soontra to sign in and approve | You create a key in Settings and paste it into the tool |
| How many | One connection per person | Up to 25 active keys per workspace |
| Access | An access level, plus optional boxes | A switch per scope |
| Ends when | You disconnect it, or connect another app | It expires, or you revoke or rotate it |

> **Note:** Only workspace owners and admins can connect an AI app or manage API keys. Soontra checks the role again on every request: if the person who made a connection or key is removed from the workspace or is no longer an owner or admin, it stops working.

## Sign in from an AI app

Give the app the endpoint URL. On its first request the server answers `401` and points the app to Soontra’s sign-in, following the MCP authorization spec, so an app that supports remote MCP servers needs nothing else from you.

1. **The app opens Soontra in your browser. Sign in if you are not already.**

2. **Choose the workspace to connect.**

3. **Choose an access level.** **Full access** (recommended): read the workspace and file content, see analytics, and create or edit drafts, projects and documents. **Content access**: the same, without creating or changing anything. **Read-only**: names and structure only.

4. **Open Advanced options to change individual scopes.** **Download files** is not part of any access level. Tick it if the app should show previews, play media or make download links.

5. **Choose Authorize.**

### One connection per person

Each person has one signed-in connection at a time, to one workspace. Signing in from a second app, or to a second workspace, replaces the earlier connection. The earlier app then gets `401` with a message asking you to reconnect. API keys are separate and are not affected.

### For client developers

- An unauthenticated request gets `401` with `WWW-Authenticate: Bearer realm="soontra-mcp"`, a `resource_metadata` URL and `scope="offline_access"`.
- The protected resource metadata (RFC 9728) is at `https://app.soontra.com/.well-known/oauth-protected-resource/api/mcp`. It names the authorization server, which publishes its own metadata and supports dynamic client registration.
- Request `offline_access` to receive a refresh token.
- The scopes a connection has are the ones approved on Soontra’s screen, not the ones in the token request.

## API keys

1. **In Soontra, open **Settings**, then **API & MCP**, and switch to **API**.**

2. **Choose **Create New**.**

3. **Name the key and set what it may do.** A name (up to 80 characters), an optional expiry date, a switch for each scope (`read` is always on), and an optional list of up to 20 IP addresses or CIDR blocks the key may be used from.

4. **Copy the key.** It is shown once. Soontra stores only a hash, so a lost key cannot be recovered: create another.

### Sending a key

```http
Authorization: Bearer soontra_sk_live_...
```

- Keys start with `soontra_sk_live_`.
- Send the key in the header only. A key in a query string is refused.
- Treat a key like a password: keep it out of chats, shared config files and version control.

### Rotating and revoking

- **Rotate** makes a new key with the same name and scopes and revokes the old one. The new key is shown once.
- **Revoke** stops a key at once and cannot be undone.
- The workspace owner can revoke every key at once.
- A workspace can hold 25 active keys. Revoke one to make room for another.

## When authentication fails

A missing, wrong, expired or revoked credential always gets the same `401`, so a caller cannot tell which it was. See [Errors](https://soontra.com/docs/errors).