# Authentication

This page covers access to the OnEarly MCP server. Webhooks don't use these credentials: each delivery is signed with the webhook's own secret. See [Verifying signatures](./webhooks.md#verifying-signatures).

Every request to the MCP server carries a credential in the `Authorization` header:

```http
Authorization: Bearer <credential>
```

There are two kinds of credential:

- **API keys**, which you create in the OnEarly app and keep on your own server.
- **OAuth access tokens**, which an app gets when a person approves it under **Connected apps**.

| Credential | Acts as | Where it works | Created by |
|------------|---------|----------------|-----------|
| [Group API key](#group-api-keys) | The group | MCP server | A member who can manage the group |
| [Personal API key](#personal-api-keys) | You | MCP server | You |
| [Connected app](#connected-apps-oauth) token | The person who approved the app | MCP server | The app, after the person approves it |

## API keys

### Key format

API keys look like this:

```text
oe_sk_live_au_3f9a1c0e7b2d4a6f8e1c3b5d7a9f0e2c
```

| Part | Meaning |
|------|---------|
| `oe_sk_` | Marks the value as an OnEarly secret key. |
| `live` or `test` | `live` for production keys, `test` for keys from any other environment. |
| region | The home region of the key's account or group. Treat it as opaque; don't parse it or route on it. |
| 32 hex characters | The secret part. |

Keys created before regions were added have no region segment (`oe_sk_live_<hex>`). They keep working.

A key's value is shown **once**, when you create it. Copy it straight into your secret store. Afterwards the app shows only the last four characters, so you can tell keys apart.

### Group API keys

A group API key lets an MCP client act as a group, within the key's scopes.

- **Create** keys under the group's settings, in **Developer**. You need the group's `manage-group` permission. The Admin role always has it, and a group's own roles can include it; see [Group roles](/core-model/actors#group-roles).
- **List** the group's keys to see each one's scopes and when it was last used.
- **Revoke** a key at any time. It stops working straight away.
- **Expiry** is optional. Set an expiry date when you create the key, and rotate before it passes. A key given an expiry date in the app keeps working until the end of that day in your time zone.

:::warning[Keep group keys on your server]
A group key can do anything its scopes allow, as the group. Never put one in a mobile app, a browser or a public repository. If your users need to act through your product, have your backend check who they are first, then call OnEarly with the key.
:::

### Personal API keys

A personal API key lets an MCP client act as you. Create keys under **Account → Developer → Personal API keys**. That page also shows your MCP address and a ready-to-paste configuration for MCP clients.


### Scopes

Scopes narrow what a key can do. They never widen it: a key can only do what its account or group could already do, and scopes take away the rest.

Every key has at least one scope, and can do only what its scopes name. For full access, give the key the `*` scope on its own. Pick the scopes when you create the key; the key list shows them afterwards. You can't change a key's scopes later. Create a new key instead.

| Scope | Allows |
|-------|--------|
| `*` | Full access: everything the key's account or group can do. It stands alone, so a list with `*` and another scope is refused. |
| `content:read` | MCP tools that search, read and export content, list content types, explain sharing and manage saved search views. |
| `content:create` | MCP tools that create content. |
| `content:share` | The MCP tool that shares content. |
| `group:list` | MCP tools that list your groups and summarise them. |
| `group:create` | The MCP tool that creates a group. |
| `connector:<connector-id>:tool:<tool>` | One tool of one connected account, such as a connected mailbox. `<connector-id>` is the connector's UUID in lower case. |

Some MCP tools, such as those that manage groups and fill in forms, have no narrower scope and need `*`. The [MCP server](./mcp.md#tools) page shows which scope each tool needs.

An empty, unknown or malformed scope list, or `*` with another scope, is refused with `400 INVALID_SCOPES`.

## Connected apps (OAuth)

Connected apps are applications a person has allowed to use their OnEarly account, for example an AI assistant working through OnEarly's tools. They use OAuth 2.0, so the app never sees the person's sign-in details and the person can take access back at any time.

Connected apps reach OnEarly through the [MCP server](./mcp.md).

### How an app connects

Diagram: [How an app connects](https://docs.onearly.com/diagrams/api-authentication.html)

1. **Discover.** The app reads the protected resource metadata at `https://api.onearly.com/.well-known/oauth-protected-resource/mcp`. It names OnEarly's authorisation server and the supported scopes.
2. **Authorise.** The app sends the person to sign in using the authorisation code flow with PKCE (`S256`). It must name the MCP server as the resource (`resource=https://api.onearly.com/mcp`, [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)). A request without the resource is refused.
3. **Consent.** The person signs in to OnEarly and sees what the app is asking for. They choose **Allow** or **Deny**.
4. **Call.** The app exchanges the code for an access token and calls the MCP server with it.

**Example: Send the person to sign in**

The authorisation and token endpoints come from the metadata of the authorisation server that the protected resource metadata names.

Request:

```http
GET /oauth2/auth?response_type=code&client_id=example-assistant&redirect_uri=https%3A%2F%2Fassistant.example.com%2Fcallback&scope=mcp%3Atools%20offline_access&resource=https%3A%2F%2Fapi.onearly.com%2Fmcp&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&state=af0ifjsldkj HTTP/1.1
Host: auth.onearly.com
```

**Example: Exchange the code for tokens**

Request:

```http
POST /oauth2/token HTTP/1.1
Host: auth.onearly.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=8kQ2vX7pLm4nR1sT&redirect_uri=https%3A%2F%2Fassistant.example.com%2Fcallback&client_id=example-assistant&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

Response:

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImV4YW1wbGUifQ.eyJzdWIiOiJleGFtcGxlIn0.c2lnbmF0dXJl",
  "expires_in": 3600,
  "refresh_token": "Zx9cV3bN6mQ1wE4rT7yU2iO5",
  "scope": "mcp:tools offline_access",
  "token_type": "bearer"
}
```

Most MCP clients do all of this for you when you add `https://api.onearly.com/mcp` as a server.

### OAuth scopes

These are the only scopes OnEarly grants. Anything else an app asks for is dropped. The consent screen describes each one in plain words.

| Scope | Shown to the person as | What it gives the app |
|-------|------------------------|----------------------|
| `mcp:tools` | Full access to OnEarly as you | Use the MCP tools as the person. Required on every MCP request. |
| `openid` | Confirm who you are | A stable identifier for the person. |
| `email` | See your email address | The person's email address, if they have one. |
| `profile` | See your name | The person's name, if they've set one. |
| `offline_access` | Stay connected | A refresh token, so the app keeps access without asking again until the person revokes it. |

Without `offline_access`, the app's access ends when its session expires and it has to ask again.

### Managing connected apps

People see and manage their connected apps under **Account → Connected apps**:

- Each app shows its name and when it was last used.
- Apps OnEarly has verified carry a **verified** badge.
- **Revoke** stops an app's access straight away. It has to ask again to reconnect.

OnEarly's own apps can't be revoked here.

## Authorisation errors

The MCP server answers a missing or refused credential the OAuth way. See [MCP authorisation](./mcp.md#authorisation).

Source: https://docs.onearly.com/api/authentication/
