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.
Every request to the MCP server carries a credential in the Authorization header:
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 | The group | MCP server | A member who can manage the group |
| Personal API key | You | MCP server | You |
| Connected app 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:
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-grouppermission. The Admin role always has it, and a group's own roles can include it; see 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.
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 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.
How an app connects
- 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. - 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). A request without the resource is refused. - Consent. The person signs in to OnEarly and sees what the app is asking for. They choose Allow or Deny.
- Call. The app exchanges the code for an access token and calls the MCP server with it.
The authorisation and token endpoints come from the metadata of the authorisation server that the protected resource metadata names.
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
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
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.