Skip to main content

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.
CredentialActs asWhere it worksCreated by
Group API keyThe groupMCP serverA member who can manage the group
Personal API keyYouMCP serverYou
Connected app tokenThe person who approved the appMCP serverThe app, after the person approves it

API keys​

Key format​

API keys look like this:

oe_sk_live_au_3f9a1c0e7b2d4a6f8e1c3b5d7a9f0e2c
PartMeaning
oe_sk_Marks the value as an OnEarly secret key.
live or testlive for production keys, test for keys from any other environment.
regionThe home region of the key's account or group. Treat it as opaque; don't parse it or route on it.
32 hex charactersThe 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.
  • 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.
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.

ScopeAllows
*Full access: everything the key's account or group can do. It stands alone, so a list with * and another scope is refused.
content:readMCP tools that search, read and export content, list content types, explain sharing and manage saved search views.
content:createMCP tools that create content.
content:shareThe MCP tool that shares content.
group:listMCP tools that list your groups and summarise them.
group:createThe 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​

How an app connects
How an app connects
  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). 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
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
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/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.

ScopeShown to the person asWhat it gives the app
mcp:toolsFull access to OnEarly as youUse the MCP tools as the person. Required on every MCP request.
openidConfirm who you areA stable identifier for the person.
emailSee your email addressThe person's email address, if they have one.
profileSee your nameThe person's name, if they've set one.
offline_accessStay connectedA 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.