Sign-in and errors

Store an API key once

Any acting member, a teammate, co-owner or Owner, person or machine, can connect a new tool without changing Mainmind's code. Use an api-key/v1 account when the provider accepts an API key in an HTTP header. Mainmind stores the key encrypted and injects it into calls to the installed API destination. Subsequent bots use the alias; the key is absent from their permits, local environments and account receipts.

When a human holds the secret

An agent usually does not hold the key, and should not carry it through a chat. Add the account without it: call install_provider_connection with alias and profile and no credential. The account is written pending and the receipt returns a single-use placement_url, valid seven days, that the agent sends to an Owner or co-owner of the space.

That person opens the link in a browser signed in with GitHub. The page, titled Connect followed by the provider or alias and the space, shows where these details are sent, and who asked when an actor name was recorded — an install that recorded only a seat names nobody rather than presenting that seat as a person. Where they are sent is the exact origin, path and header for an API key; for a sign-in the token endpoint as well, and any header bound to a slot. All of it is fixed when the account was added and unchangeable afterwards. An account of keys for a tool (secret-slots/v1) takes values the same way. The page says no tool receives them and nobody can read them back. To use those values from a tool, remove the account and add it again as a driver a tool can call, as Move an account off secret-slots shows. Then one write-only input per field, each with a plain label and a one-line hint and never a prefilled value. When they press Connect, what they typed is stored encrypted on the server, the account becomes active, and the link stops working. Nothing typed is returned to the agent, logged, or written to a run receipt. A teammate, a member of another space, or anyone with a used, expired or invented link sees a page that says only that the link is not valid.

list_provider_connections lists a pending account under pending with who asked and when the link expires, and lists it as active once the values are placed; an Owner's or co-owner's start carries the same under open_placements, including a pending account of keys for a tool. Neither carries the link. An Owner or co-owner signed in to the dashboard can also place the values by alias with POST /api/tool-connections/<alias>/place, without a link.

The app's Accounts screen lists this space's own accounts and nothing else: one card per alias with its state, who added it, and each value name shown as saved or needed, never a value. One that is not connected yet carries Connect, including keys a tool keeps by name. An active api-key/v1 one carries Replace key. An active sign-in, app login, or named-keys account carries Replace values. Named keys say that no tool receives them and nobody can read them back. Any of them carries Remove behind a confirmation. Add an account adds one from the app through the same routes an agent uses. The built-in provider adapters (Amazon Selling Partner, Zoho, Shopify) appear there once connected, and under Add an account until then; Amazon signs in instead (Sign in with Amazon). A placed one carries Replace values: type only what changed, such as a client secret you rotated at the provider, and leave the rest blank to keep what is stored. It stays the same provider account, agents use the new values from their next call, and nothing about the account has to be removed first. Over HTTP it is PUT /api/tool-credentials with the generation the status route lists.

Add an API key from Accounts

Choose Add an account; API key is already chosen. Fill in:

• Name: what you call it, such as Internal billing API. Tools call it by the name shown under it, here internal-billing-api.
• Website: the API's address, such as api.example.com. An https address works too. The key is sent only there. A path, a port other than 443, plain http or an IP address is refused.
• Header: starts as Authorization. Change it to the header the service reads, such as X-Api-Key, and clear Prefix for a header like that. The form clears it for you; type a prefix again if the service wants one.
• Prefix: starts as Bearer, which sends Authorization: Bearer <key>. Leave it empty when the service wants the key alone.
• Key: the key itself.

Press Connect. Tools send the whole path on each call, such as /v1/invoices; the account's API root is /. One key covers one website: for a second website, add a second account.

If the service answers a call with 401, the card says Key refused: the service refused this key on that date, and Replace key takes a new one. Mainmind keeps only the date and the status, never the answer. The mark goes away after the next call that works, or once the key is replaced.

To remove an account, an Owner or co-owner calls revoke_provider_connection from their AI app, or chooses Remove on the account's card; over HTTP, DELETE /api/tool-connections/<alias> takes the machine bearer or an Owner's or co-owner's signed-in dashboard session. The alias is free again and the row stays as the audit record. Remove an account that is not connected yet when its destination is not the service you expect, rather than entering anything on it.

For example, this profile contains only configuration, so it can live with the tool's instructions:

{
  "schema": "mainmind.connection-profile/v1",
  "id": "new-api",
  "driver": "api-key/v1",
  "api_origin": "https://api.example.com",
  "api_root": "/v1",
  "authorization_header": "x-api-key",
  "request_headers": ["content-type"],
  "response_headers": ["content-type"]
}

Replace the example origin and root with the provider's API address. For an API that requires Authorization: Bearer, set authorization_header to authorization and add authorization_scheme: "Bearer". Keep the credential out of this file. The credential object is exactly { "api_key": "…" }; the key must contain 8–4096 printable non-space ASCII characters.

When the agent itself holds the key outside a chat, install with install_provider_connection, passing an alias, the profile and the credential. This is write-only: the result returns field names and a non-secret credential_generation, never the key. An existing alias returns HTTP 409. Mainmind does not put the credential payload in its run ledger, but a chat host may retain the input. To keep the initial key out of a bot conversation, install without a credential and let a person type it on the placement page (When a human holds the secret), or send it directly over HTTPS to POST /api/tool-connections from a program that reads the key from a hidden prompt. Neither the Owner machine bearer nor the provider key belongs in a command argument or environment variable.

Then any acting member's bot calls list_provider_connections and uses the returned identifier:

{
  "provider": "connection:new-api",
  "method": "GET",
  "path": "/items"
}

Pass that object to call_provider. The request reaches https://api.example.com/v1/items with the key injected by Mainmind. Local tools can instead obtain issue_tool_permit and use the returned MAINMIND_CONNECTIONS_URL plus /new-api/items, authenticating with MAINMIND_CONNECTIONS_KEY. That value is a Mainmind permit, not the provider key. The tool must support this gateway URL; Mainmind does not host its executable code.

A request body must state its own type. call_provider forwards your body unchanged and adds no content-type of its own, so send one in headers — {"content-type": "application/json"} for JSON, or whatever the provider documents for that route. A body with no type is refused before the provider is contacted. This is not pedantry: a provider that will not parse an untyped body rarely says so, and at least one answers 200 having applied none of it, which is a write you are told succeeded and did not.

Replace a key with replace_provider_connection_credential, passing the alias, expected_credential_generation from the install receipt or fresh discovery, and the new {api_key} credential. Direct HTTPS uses PUT /api/tool-connections. To keep the new key out of a chat, an Owner or co-owner uses Replace key on the account's card on the Accounts screen instead.

Replacement never reads back the old key or changes the API destination. A stale generation returns 409. Old permits cannot use the replacement; local tools get a fresh permit. For MCP, inspect any previous operation receipt and start a fresh call without run_id; do not replay an uncertain provider write. Requests already sent cannot be recalled. If a replacement response is lost, check the current generation before retrying.

An Owner or co-owner can replace an oauth2-refresh/v1 account's values the same way, with the same generation check. A teammate cannot: those values sign in to the provider for the whole space, so a teammate asks one of them instead. The best route is Replace values on the app's Accounts screen, which keeps the refresh token out of a chat. Over MCP or HTTPS, send the whole credential, exactly as an install requires: client_id, client_secret, the new refresh_token, tenant_id when the profile binds one, and every declared slot. Or send {refresh_token} alone: the installed client, tenant and slots are kept, and never returned. A bound tenant_id must be the one the account was added with; to move to another tenant, revoke and install again. The alias, profile and grants stay as they are. The next call mints its access token from the new refresh token; the one cached from the old grant is not used again. An account added with secret-slots/v1 keeps its values with Mainmind. An Owner or co-owner places them with Connect while it is pending, or Replace values once it is connected. The values go into the store and are not shown back, and no tool receives them. To use it from a tool, revoke it and add the account again as an app login (sign-in/v1), an API key (api-key/v1) or a sign-in (oauth2-refresh/v1) with lease_env, as Move an account off secret-slots shows.

Install only the provider destination you intend to trust with its key. Mainmind does not follow redirects and refuses responses that reflect the key verbatim, but cannot protect against a malicious provider encoding a key into its own response. API-key accounts support one authentication header. OAuth refresh uses oauth2-refresh/v1. No tool permit carries an account's values: inject_access_token is refused for new accounts. secret-slots/v1 may be added, and its values placed or replaced; a permit still names it, and an account with inject_access_token, in connections_omitted and does not receive the values. When a refresh answers invalid_grant, the provider has revoked or expired the grant and retrying will not help. For Zoho, an owner or co-owner presses Sign in with Zoho. For another provider, they use Replace values on the Accounts screen, or replace the values over MCP or HTTPS as above. Revoking it and installing it again also works. A Google OAuth app left in Testing status expires its refresh tokens after 7 days, so publish it to Production. An unauthorized_client answer means the provider refused the OAuth client itself; fix the client with the provider, then replace the values the same way. Either way only calls through that account fail; the others keep working.

Sign in with Zoho

Press Sign in with Zoho. You approve Zoho Expense, Books, Inventory or Desk in the browser, and Mainmind stores the login. You do not create a client, and you do not handle a code.

The page is https://mainmind.app/oauth/zoho/connect. Add alias for an account that is already waiting, or provider=zoho-desk or provider=zoho-inventory for those built-in accounts. When you belong to more than one space, add workspace with the space’s name. A placement link for a Zoho account opens the same button.

Zoho Expense asks for full access to Expense. Books, Inventory and Desk each ask for that product only. India uses accounts.zoho.in. Other Zoho data centres use their own accounts host, and Mainmind picks the host from the account.

An agent can still pass credential {authorization_code} on replace_provider_connection_credential, with expected_credential_generation from list_provider_connections, when a code is already in hand. Built-in accounts — Zoho Desk, Zoho Inventory, Shopify and Amazon — use provider and that generation. The generation is a 64-character id, and the decimal generation still works. Mainmind checks that Zoho accepts the login, and only then replaces what is saved. A refusal keeps the previous login. The slot keeps one login, so there is no older one to restore.

Shopify and Amazon do not take a Zoho code. A replacement that Zoho, Shopify or Amazon refuses is not saved, and the previous login stays.

Access tokens from a saved login are kept until shortly before they expire, and every caller of that login shares them. A burst of calls does not mint a new token each time. When Zoho limits new tokens, Mainmind waits and says when to retry. The message includes Zoho’s own error, so a limit is distinct from a code Zoho rejected.

Adding, listing, API-key replacement and call_provider are open to the acting roles, teammate, co-owner and Owner; replacing oauth2-refresh/v1 values is for an Owner or co-owner. Any of them may add an account, passing its values when they hold them; when they do not, an Owner or co-owner places them (When a human holds the secret). A co-owner is an operational peer (Roles), so they hold the Owner's tool lease: the built-in provider adapters (Zoho, Amazon, Shopify), read and write, and every account, on the local permit and the server-side one alike. A teammate's local permit stays Git-only until each tool declares the capabilities it needs; their server-side permit carries the active accounts. Business actions still follow the space's Process and Authority.

Save Zoho Expense

Save a Zoho Expense login for India. An Owner or co-owner sends the account alias, the account type zoho-expense, the region in, and the three login fields client_id, client_secret and refresh_token.

Mainmind asks accounts.zoho.in, then reads Expense at www.zohoapis.in. The login is stored only when Zoho accepts it. The answer lists each field's length in bytes and its SHA-256, and it does not include the value. To change that login later, send the generation number from that answer with the new fields.

If Zoho does not accept the login, nothing new is stored and the previous save stays. Correct the three fields and send them again.

An agent holding the owner's connection calls issue_gateway_seal with alias, preset set to zoho-expense, and region set to in. Send no login fields. Mainmind answers with an address ending in /api/gateway-secrets/seal and a key. A shell posts one JSON object of the three fields to that address. The key goes in the header X-Mainmind-Seal-Key, not in the address and not in the body. Replace the capitals with the login Zoho already gave you. The answer is the same lengths and SHA-256. If Zoho does not accept the login, that link can be used again.

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

Shopify, Amazon, Zoho Inventory and Zoho Desk still use Accounts. This does not move them.

An Owner or co-owner, already signed in, can send the same login without that link. The request is JSON to POST https://mainmind.app/api/gateway-secrets. Replace the capitals with the login Zoho already gave you.

{
  "alias": "zoho-expense",
  "preset": "zoho-expense",
  "region": "in",
  "fields": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }
}

Move an account off secret-slots

An account added with secret-slots/v1 gave its values to a tool on your computer. No permit carries them now, so issue_tool_permit names that account in connections_omitted. To use it again, move it to a driver Mainmind calls for the tool:

1. Before anything changes, note two things: the slot names list_provider_connections shows for the old account, and the variable names the tool reads. The old slot names are gone once it is revoked.
2. Ask an Owner or co-owner to change the password or secret at the provider. Earlier permits copied the old values onto computers, and those copies keep working until they are changed. Remove the old values from the tool's settings.
3. An Owner or co-owner revokes the old account with revoke_provider_connection. Its alias is free again once it is revoked.
4. Install it again with no credential, in one of the shapes below. The receipt carries a placement_url. Send it to an Owner or co-owner, say which values go in each box (the shapes below say), and they paste the new values once.
5. Call issue_tool_permit. Its commands.environment sets the lease_env names. base_url is this account's address on Mainmind, standing for api_origin plus api_root: the tool adds its usual paths to it. ticket is the permit: the tool sends it as a Bearer token in its Authorization header, where it used to send its own token. Each sentinel is a name the tool insists is set, such as a password variable it checks before it starts, and gets the text mainmind. Use the names the tool reads. A permit lasts at most an hour; call issue_tool_permit again for a new one.
6. The tool skips its own login: Mainmind logs in and adds the real token to each call. A call through Mainmind to the account's login address is refused before it leaves, so the tool's placeholder text never reaches the login. A tool that cannot take its API address from a variable needs that change first.
7. Make one read call through the tool to check it.

An account that hands out a token after a login, with an email and password or a client ID and secret, is sign-in/v1. Mainmind sends those values only to the login address, which must be on the same origin as api_origin, and never puts them in an API call.

Shiprocket signs in with an API user, not the login you use for the Shiprocket panel. An Owner or co-owner makes one under Settings, then API, then Configure, with its own email and password, and pastes those:

{
  "alias": "shiprocket",
  "profile": {
    "schema": "mainmind.connection-profile/v1",
    "id": "shiprocket",
    "driver": "sign-in/v1",
    "slots": ["SHIPROCKET_EMAIL", "SHIPROCKET_PASSWORD"],
    "sign_in": {
      "url": "https://apiv2.shiprocket.in/v1/external/auth/login",
      "format": "json",
      "fields": { "email": "SHIPROCKET_EMAIL", "password": "SHIPROCKET_PASSWORD" },
      "token_field": "token"
    },
    "api_origin": "https://apiv2.shiprocket.in",
    "api_root": "/v1/external",
    "request_headers": ["content-type"],
    "response_headers": ["content-type"],
    "lease_env": {
      "base_url": "SHIPROCKET_BASE_URL",
      "ticket": "SHIPROCKET_TOKEN",
      "sentinels": ["SHIPROCKET_PASSWORD"]
    }
  }
}

FedEx signs in with the API Key and Secret Key of a project in the FedEx Developer Portal: paste the API Key as the client ID and the Secret Key as the client secret. Its account number goes in request bodies, not in the login, so it is not one of the pasted values: the tool keeps it in its own settings. An account number is not a key.

{
  "alias": "fedex",
  "profile": {
    "schema": "mainmind.connection-profile/v1",
    "id": "fedex",
    "driver": "sign-in/v1",
    "slots": ["FEDEX_CLIENT_ID", "FEDEX_CLIENT_SECRET"],
    "sign_in": {
      "url": "https://apis.fedex.com/oauth/token",
      "format": "form",
      "fields": { "client_id": "FEDEX_CLIENT_ID", "client_secret": "FEDEX_CLIENT_SECRET" },
      "constants": { "grant_type": "client_credentials" },
      "token_field": "access_token",
      "expires_in_field": "expires_in"
    },
    "api_origin": "https://apis.fedex.com",
    "api_root": "/",
    "request_headers": ["content-type"],
    "response_headers": ["content-type"],
    "lease_env": { "base_url": "FEDEX_BASE_URL", "ticket": "FEDEX_ACCESS_TOKEN" }
  }
}

Mainmind keeps that login's token and uses it on later calls until the login says it expires. When the login does not say, the token is kept for ten days. Shiprocket's login does not say, and its token lasts ten days. One login runs at a time, so two calls together do not sign in twice.

A call the account answers with 401 signs in again. A login the account answers with 429, or with 500 through 599, or that times out or cannot be reached, is tried once more and does not stop the account. The password is sent exactly as it was saved. A login that answers 401 or 403 stops the account, unless that answer says the problem is the token, such as invalid token. Accounts then shows that status, a short message with any password or token removed, and when a login last succeeded. Details lists recent logins and calls, with the time and the outcome, and never a password or token. An Owner or co-owner presses Try the saved login to use the stored password once, or Replace values to enter a new one.

An owner or co-owner's assistant can try that saved login without anyone typing the password into the chat. It calls retry_provider_sign_in with the account's alias. When the saved login works, the next call goes through. When the account refuses it again, the assistant does not type the password into the chat and does not ask for another try. It asks for a reseal link and posts the current password to that link from the environment.

To enter a new password or API key, the assistant calls replace_provider_connection_credential with request_reseal_link set and no values. Mainmind answers with one link that lasts ten minutes. The assistant posts one JSON object to that link from the environment. The keys are the names the account already uses, such as SHIPROCKET_PASSWORD or api_key, and the values never go through the chat. The link works once.

Add any other header the tool must send to request_headers.

An account that signs in with OAuth and a refresh token, such as Zoho or Google Ads, is oauth2-refresh/v1: the same steps apply, with header_slots for any value the provider wants in a header and lease_env for the tool, as in the Google Ads shape under Optional tasks and automatic provider receipts. If it needs a new refresh token, follow Get a new refresh token.

Get a new refresh token

When the Accounts screen says a login stopped, the provider no longer accepts the sign-in behind that connection. For Zoho, press Sign in with Zoho on that card. For another provider, sign in again in the same app that connected it the first time, with the same client. An owner or co-owner then uses Replace values on the card. If you did not set it up, send this section to whoever did, or ask your AI assistant to walk you through it.

A Google app left in Testing status expires its refresh tokens after 7 days. Publish it to Production in the Google Cloud console so the next one lasts.

If the card says the provider stopped accepting the connection's client, the client ID or secret no longer works. Fix or create the client with the provider, sign in again with that client, then enter the new values in Replace values.

Sign in with Amazon

The built-in Amazon Selling Partner account does not need a refresh token typed in. An Owner or co-owner signs in with Amazon, and Mainmind gets the refresh token itself.

1. Open Accounts. Choose Add an account, then Amazon Selling Partner, or Sign in again on the Amazon card when it is already connected.
2. In your app in Seller Central, add the two addresses the dialog shows: https://mainmind.app/oauth/amazon/login as the OAuth Login URI and https://mainmind.app/oauth/amazon/callback as the OAuth Redirect URI.
3. Choose the Amazon store you sell on, then paste your app's ID (amzn1.sp.solution.…), client ID and client secret. They are under Seller Central, Apps and Services, Develop Apps, your app, View (LWA credentials). When Amazon is already connected, leave the client ID and secret blank to keep the ones saved.
4. Press Sign in with Amazon, approve the app in Seller Central, and you come back to a page that says Amazon is connected. If Amazon sends the sign-in somewhere else, that page names the HTTP status and api.amazon.com, nothing is stored, and you start again from Accounts.

The store sets the region: India and the European stores use Europe, the Americas use North America, and Japan, Australia and Singapore use the Far East. Signing in again must use a store in the same region as the account already connected. A sign-in works once, for fifteen minutes, and only in the browser that started it. Your agent can use Amazon from its next call. Over HTTP the start is POST /api/tool-credentials/amazon/sign-in; see the HTTP API.

Connect a person or a machine

A personal connection uses OAuth. Every space has its own connection URL, https://mainmind.app/mcp/<workspace> — the Setup screen shows yours, with a one-click copy. Point an MCP client at it and the authorization is fixed to that space before it begins. The plain https://mainmind.app/mcp resource also works: everybody — Owner, co-owner, teammate or viewer — continues with GitHub, and Mainmind resolves the space from that GitHub account's live membership, offering a choice if it holds more than one. Either way the resulting OAuth grant connects exactly one space and is refused at every other space's connection URL. The plugin ships no secrets, and Mainmind never hands an invited member a GitHub credential of its own.

Repository custodians signing in through the website use GitHub at /start. Initial repository claim separately requires GitHub-reported admin permission; ordinary sign-in only resolves an existing Owner and never promotes a collaborator. A person whose GitHub account is not bound to a membership yet joins through their invitation first, below. A persistent agent normally uses that person's role-following OAuth connection and selects its stable profile on each supported MCP call; it does not receive the person's token or a separate login. Persistent agents owns profile registration and reuse. An agent that already has a key keeps using it. A person's invitation is a one-time /join link, not a login: it carries at least 128 bits of randomness, expires seven days after the Owner confirms it, and is redeemed once — by opening it and signing in with GitHub, which binds that GitHub account to the membership, permanently. The Team screen shows the exact deadline and stops revealing an expired link. The code is never typed on the authorization page; every later authorization for that member, on any client, is the ordinary Continue with GitHub.

No tool accepts a space name, and a call cannot answer from a space other than the one its connection is serving: a grant made for one space's connection URL is refused at every other space's.

Which space a connection serves is a property of the connection, and use_organization is the only thing that changes it. Connect at https://mainmind.app/mcp with your full member role and the connection holds every space you belong to, with the role each one grants, serving one at a time. Spaces you join or create later join it too, and leaving a space ends its access there. To give an assistant one space only, connect it at that space's own connection URL instead. Call use_organization with no argument to see them, with a space name to switch; the next call runs on the new space with no reconnecting (reload the tool list if your role there differs), and start must run again because nothing you read from one space is true of another. Each space's live role decides its own ceiling, so being an Owner of one grants nothing in another. A connection made at a space's own connection URL serves that space and cannot switch.

Signing in again after the sign-in upgrade

Mainmind's sign-in moved to a stricter version. Most connections need nothing. Some sign in once more:

• A connection made earlier with a space's own connection URL, or with https://mainmind.app/mcp/ ending in a slash, is asked to sign in again. Sign in at the same address; the new connection reaches the same space or spaces as before.
• A connection made earlier with just https://mainmind.app, with nothing after it, is asked to sign in again. Mainmind no longer answers sign-in questions at that address, so sign in at https://mainmind.app/mcp. An app that follows Mainmind's sign-in prompt finds that address by itself.
• An app that registered itself with Mainmind must use return addresses that start with https://, or with http:// on your own computer (localhost, 127.0.0.1 or [::1]). An app registered with any other http:// address is refused at its next sign-in and must register again.

When a sign-in is refused and the app's return address is one it registered, Mainmind sends the refusal back to the app, so the app stops waiting.

An app names the same Mainmind address when it finishes or renews a sign-in as when it started it, or names none. Naming a different space's address at that point is refused; to reach another space, sign in at its address.

Choose personal connection access

A personal connection follows your role. Signing in without naming scopes proposes it, and a client may also request mainmind:member.role by name. Consent allows that client to follow your live Mainmind role in this space. An Owner connection includes team administration; a teammate or viewer stays within that member's current access. Later role and knowledge-access changes apply to the connection, and revoking the member stops access. This permission does not approve a business action or create a role.

Owner-connected profiles use this permission as their authority ceiling; the profile itself adds none. Existing limited grants stay limited until a fresh authorization receives explicit consent. Check the live surface before using a newly released operation. An authenticated call establishes what this connection can do. Real Codex/Grok continuation still requires its own authenticated work and read-back evidence.

OAuth scopes

You do not need to name scopes. A connection that names none proposes mainmind:member.role on the consent screen: after Allow it follows the person's live role, whatever that role is. Name scopes only to give a client a narrower ceiling than your role on purpose. The supported scopes are:

Existing connections retain the scopes already approved. Token refresh does not add mainmind:member.role or widen that grant. An Owner on an older limited grant migrates with one fresh connection: disconnect the old authorization, connect again without naming scopes, and approve your member role on the consent screen. The same applies to anyone on an older limited grant. An explicit limited scope request stays limited. Mainmind shows the client and requested permission before Allow; opening an authorization link grants nothing.

Owner-only team operations carry MCP write/destructive annotations. Changes to people's access use Mainmind's confirmation flow: the tool creates a 15-minute proposal for review. If a limited grant lacks the required team scope, Mainmind responds with 403 insufficient_scope. The body names the exact missing scope (required_scope) and its documentation URL (docs). A WWW-Authenticate challenge lets a capable host ask the person to reauthorize. Requesting a wider scope never turns a viewer, teammate, or co-owner into an Owner. A co-owner cannot administer the team; live membership and knowledge scopes are checked again on every operation. Completing the step-up is the same authorization every human uses, again, for the wider scope: continue with the GitHub account already bound to the membership. Mainmind first shows the exact client ID and eligible scopes and requires an explicit Allow; an authorize link alone grants nothing. It then reloads the live role ceiling for the new grant.

People can also be invited from the authenticated Team screen. Owner-connected profile registration uses the person's work permission and needs no team-management grant. Legacy machine enrollment requires an Owner connection with effective mainmind:team.manage.

Recover a connection that cannot request team access

For an existing limited grant, your current role and the permissions approved for your assistant both apply. The role-following option above requires its own explicit consent; it does not repair old tokens in place. An Owner connection that explicitly requested limited scopes stays limited: signing in as Owner does not widen a grant that named its ceiling. A scope upgrade requests the missing permission together with existing access; Mainmind still shows the exact grant before you approve it. Anyone who connects without naming scopes is offered their own member role instead of this recovery; use the steps below only to repair a grant that must stay on explicit operation scopes, or to deliberately limit one.

If your host reports 403 after trying upscoping, refreshing the old token may have returned the same basic permissions without opening consent. Repeating that refresh cannot grant new access. Start a fresh authorization that explicitly requests the required scopes. For Owner team management, request:

mainmind:org.read mainmind:org.work mainmind:team.read mainmind:team.manage

Only request team permissions for a connection you intend to use for team management. For a roster read alone, add mainmind:team.read without mainmind:team.manage. A non-Owner cannot acquire team access this way.

Cursor

Cursor documents explicit scopes under static OAuth configuration; an auth object containing only scopes is not sufficient. It requires a registered CLIENT_ID. See Cursor's OAuth configuration.

If you already have a public OAuth client registered for Cursor with the correct callback, reuse its client ID. Otherwise, the following Node command registers a public client with Mainmind. It creates a client registration only, not a membership or access grant, and prints only the client ID:

node --input-type=module <<'JS'
const response = await fetch('https://mainmind.app/register', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    client_name: 'Cursor Mainmind',
    redirect_uris: ['http://localhost:8787/callback',
      'https://www.cursor.com/agents/mcp/oauth/callback'],
    token_endpoint_auth_method: 'none',
    grant_types: ['authorization_code', 'refresh_token'],
    response_types: ['code']
  })
});
if (!response.ok) throw new Error(`Registration failed: HTTP ${response.status}`);
const result = await response.json();
if (!result.client_id) throw new Error('Registration returned no client ID');
console.log(result.client_id);
JS

Edit the existing Mainmind entry in your Cursor MCP configuration, retaining its space URL and other entries. Substitute the registered client ID:

{
  "mcpServers": {
    "Mainmind": {
      "url": "https://mainmind.app/mcp/<space>",
      "auth": {
        "CLIENT_ID": "<registered-client-id>",
        "scopes": [
          "mainmind:org.read",
          "mainmind:org.work",
          "mainmind:team.read",
          "mainmind:team.manage"
        ]
      }
    }
  }
}

Disconnect this connection's old authorization in Cursor, then authorize it again. Verify the intended space and client and that Mainmind's consent screen lists the requested team permissions before allowing the connection. If it still shows only basic permissions, stop: Cursor has not used the intended configuration. Do not keep approving the same basic grant.

After connecting, start ordinary work in this space with one start call; start({}) is valid, and no whoami preflight is needed. Call list_members to test team access without inviting anyone. An invitation is a separate action that still needs the applicable approval. Static configuration is a documented Cursor capability; this recovery still needs verification in the affected Cursor installation. Do not treat a successful server test as that proof.

Connect a standing bot

A new agent joins through its owner. From the owner's own signed-in connection, reuse the exact profile from whoami, start colleagues or Owner list_members; otherwise call register_agent once with a retained UUID v4 registration key. Select the returned slug as agent on each supported call. The profile creates no credential or new grant. See Persistent agents for the full registration, adoption, presence and continuation contract.

Mainmind no longer makes new agents with their own key. invite_member invites people only, and POST /api/members, POST /api/team/invite and POST /api/team/requests/:id/approve refuse kind: "machine" with HTTP 403: "New agents join through their owner: call register_agent from your own signed-in connection. Agents that already have a key keep working."

Agents that already have a key

An agent that already holds a machine mmkey_ credential keeps working. It keeps its identity, work and access. The Owner replaces its key with rotate_member_credential and retires it with retire_members. A host change reuses that member; it does not need a new identity. Never copy a person's token into the runner. To attach such an agent to its owner instead, use adopt_agent as Persistent agents describes.

A sponsored setup invitation issued before this change can still be claimed until it expires, 15 minutes after it was issued. The runner submits the credential it generated locally:

POST /api/machine-enrollment?workspace=alder-and-ash
Authorization: Bearer <private-enrollment-invitation>
Content-Type: application/json

{"credential":"<locally-generated-mmkey-credential>"}

The activation receipt names the connection URL to use; replayed is true when the same credential is submitted again for a member that is already active. No new invitation can be made, so an expired one cannot be renewed: make the agent with register_agent instead.

A legacy scheduled bot starts over HTTP with the same functions as the MCP tools: GET /api/boot, GET /api/page-work, GET /api/work-context, and POST /api/work-session. Present a machine mmkey_ credential or a member OAuth access token. Query workspace names the space; a malformed slug is refused, never defaulted onto another space.

Owner-connected profile selection is not supported through these HTTP bearer routes. Use the MCP person connection for that profile, or keep an existing runner on the key it already has.

Authorization: Bearer mmkey_…

The deployment operator secret (FAB_TOKEN) is not a start identity. It still opens operator ledger routes such as POST /api/projection and POST /api/runs. Those operator runs do not mint a control_key and must not be used as member start. Remaining knowledge reads (search, read_node, find_process, whoami) and repository writes stay MCP. The HTTP API is the exact list.

Authorization: Bearer <operator-token>

Be aware of what that operator token is. It is a single credential held as a Worker secret for the whole deployment, not a per-customer key you can mint, scope, or rotate yourself. If you are running your own instance you set it; if you are connected to someone else's, you use OAuth or a machine member key and the operator bearer is not yours to hold. Treat it as an operator credential and keep it off anything shared.

Retire bots you no longer use

To clean up bots in one go, the Owner's assistant calls retire_members with action: "preview" and up to 25 bot slugs from list_members. Nothing changes yet: it shows each bot's owner, the job it holds on the team, open requests addressed to it, saved context and last contact. The Owner says yes once in the chat, and the assistant calls action: "confirm" with the batch_key and the Owner's reply as typed. Every bot on the list is retired together, or none is.

Retiring stops a bot's login. Its history, records and saved context stay, and nothing is deleted. It cannot be undone: to use a bot again, add a new one. action: "status" reads the receipt later. To replace a bot's key instead, use rotate_member_credential; to remove a person, use revoke_member, which still confirms in the browser.

Workspaces

Every space is a workspace. An MCP connection already knows which one it is on, and MCP tools never accept a workspace override. A signed-in GitHub session is not itself locked to one workspace: /authorize/github and the decision pages resolve the space from that account's live memberships, offering a choice when it belongs to more than one. Operator HTTP routes may use ?workspace= or a POST workspace field. A member credential is locked to the space it names; ?workspace= must match that space.

What failure looks like

Most errors come back as JSON with an error key and an HTTP status:

{ "error": "unauthorized" }

A 403 insufficient_scope also names required_scope and docs.

Decision links deliberately collapse several failures into the same unavailable result. A missing decision, wrong workspace, revoked member, wrong human role, or co-owner facing an Owner-only decision must not reveal which decision or compartment exists.

A malformed workspace is its own case. Any call carrying a workspace slug that is not lowercase letters, digits and hyphens is rejected with {"error":"bad workspace slug"} rather than quietly falling back to a default space. Rejecting instead of defaulting is deliberate: a typo must never write into somebody else's space.

Several agents on one MCP connection

These refusals are knowledge-projection contention, not an auth failure. The named strings are the contract; do not invent a queue in front of them.

A canonical write is still running. Another organizational knowledge call is still finishing: projection is busy with mcp:<tool> means another canonical write or governed operation holds this space's exclusive lease. The waiting call first waits a bounded time for that holder; if the lease is still held, this refusal is what you see. Inspect before replaying a write; the first call may already have landed. A typed deposit releases its lease after Git confirms the save. Refresh admission does not keep mcp:deposit_lesson busy after the deposit returns.

Knowledge is refreshing. Knowledge refresh in progress: or projection refresh in progress for <commit> means a rebuild or publication lease is in flight. Knowledge-dependent tools are closed until the new commit is serving. Do not answer from memory.

A read crossed a publication. the projection was republished while this read was in flight; no mixed knowledge was returned means the mixed result was discarded. Concurrent readers do not take the lease. Retry the read.

A ledger save was refused. The space or task changed before this ledger write means the publication, membership or task changed before the atomic save. Read current state, then submit the intended change again.

A save succeeded or is uncertain. The ledger change was saved or The ledger write outcome could not be confirmed means the effect succeeded or its acknowledgement was lost, and the full response could not be completed. Inspect the saved note, event or run before retrying. Retain any task receipt returned.

Read-only knowledge tools share a publication fence, so two agents can start, search and read_node at the same time. Notes, events and routine task updates can overlap canonical Git work. Canonical writes retain workspace lease and Git conflict checks, regardless of how many OAuth grants are connected. A pending land_canonical_change releases the lease while Git finishes; poll checkout_change_status with its returned landing_id. list_provider_connections, call_provider, issue_tool_permit and feedback do not take that lease. One OAuth grant authenticates one person. Distinct standing agents use their exact owned profiles on supported MCP calls; the profile adds no grant. Agents that already have a key keep their own machine identities. How to connect either path is on the Setup for each app.

One trap worth knowing before it costs you an afternoon. An unknown path under /api/ answers 401, not 404, when you are unauthenticated, because the auth gate runs before routing. A typo in a path therefore looks exactly like a broken token. Authenticate first, then read the status:

curl -s https://mainmind.app/api/nope
{"error":"unauthorized"}

curl -s -H "Authorization: Bearer $TOKEN" https://mainmind.app/api/nope
{"error":"not yet"}

Two endpoints need no auth at all, which makes them the right first call when you are checking connectivity: /api/health and /api/surface.

Limits and paging

There is no cursor or offset anywhere yet, and every list endpoint clamps silently rather than erroring, so a request for more than the maximum returns a truncated page that looks complete. The current ceilings:

POST /api/projection takes at most 500 nodes per call and 200,000 UTF-8 bytes per node. The service never truncates a node. Use mode: "sync" and the generation protocol below for a repository that needs more than one call.

A worked operator run

The operator bearer can open a run for a cron that is not a member. This is operator telemetry, not member start. A bot that needs to claim addressed work uses MCP run_start plus POST /api/work-session, or the MCP work_session tool.

Open it.

curl -s -X POST https://mainmind.app/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"task":"Reconcile yesterday","actor_label":"Nightly cron","harness":"curl"}'

{"ok":true,"run_id":"run_5b4b9603-719","started_at":"2026-08-19T14:21:34.807Z"}

Say what you are doing. Call this as you move between steps. A run that stops heartbeating shows as stalled rather than working, which is a fact derived from the clock and not a judgement about the run.

curl -s -X POST https://mainmind.app/api/runs/run_5b4b9603-719/heartbeat \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"doing":"matching payouts"}'

{"ok":true,"run_id":"run_5b4b9603-719","heartbeat_at":"2026-08-19T14:21:35.536Z"}

Close it. Use landed when the work is done, awaiting-ruling when it is parked on a decision (the run stays open and visible), conflict when the target moved, failed when it broke.

curl -s -X POST https://mainmind.app/api/runs/run_5b4b9603-719/finish \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"status":"landed","outcome":"Everything matched."}'

{"ok":true,"run_id":"run_5b4b9603-719","status":"landed"}

Putting your own knowledge in

POST /api/projection is how a space's knowledge becomes readable by every Mainmind connection. You send paths and file contents; the service parses the frontmatter, indexes the text for search, and embeds it for semantic search.

curl -s -X POST https://mainmind.app/api/projection \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "workspace": "alder-and-ash",
    "commit": "9f2a1c4",
    "mode": "replace",
    "nodes": [
      { "path": "ORG.md", "content": "# Alder & Ash\n\nWhat we do and why." },
      { "path": "processes/refunds.md", "content": "---\nkind: process\n---\n# Refunds" }
    ]
  }'

The response reports what landed, what it could not parse, and what it embedded:

{ "ok": true, "built_at": "...", "ingested": 2, "total": 2,
  "findings": [], "vectors": { "embedded_nodes": 2, "chunks": 7, "errors": [] } }

Things worth knowing before you run it:

• mode: "replace" deletes every existing node for that workspace and rebuilds from what you send. It can only ever touch its own workspace, but within that workspace it is destructive. Use merge to add or update without deleting.
• findings is not an error list. It is the parser being honest. Any frontmatter line the profile does not accept is reported rather than silently dropped, so a field that would have vanished shows up here instead.
• Send at most 500 nodes per call and at most 200,000 UTF-8 bytes per node. Oversized content is rejected before publication; it is never truncated.
• A multi-call rebuild is one fenced generation. Use mode: "sync", a stable commit, and finalize: false on the opening call. Capture the response's build_generation, then send that exact number on every later call. Set finalize: true only on the last call. Until that call completes, knowledge reads fail closed instead of serving a partial rebuild.
• A lost opening response is recoverable. Repeat the same opening request without inventing a generation. The server responds with projection_busy: true, the same target_commit, and the active build_generation; resend the chunk with that number and continue. A different or stale generation is rejected before it can mutate the projection.
• Embedding is delta based. Unchanged files keep their hash and are not re-embedded. If the semantic layer fails, search degrades to keyword matching and the failure is reported in vectors.errors rather than swallowed.
• commit is a label you supply, carried back on every answer so a reader knows which version of your files they are looking at. It is not validated.

The reference for every field is on the HTTP API page.

Runtime-channel status

/api/health reports which channels of the runtime contract are open, and it is the honest answer rather than this page. telemetry, runs, projection, surface, checkout, envelope, proposals and scopes are live. The checkout claim covers scoped current reads, typed Lesson deposits, governed create/update/delete proposals (with rename represented as one create plus one delete), governed Lesson absorption and closure, authenticated Owner approval, portable rejection, and validation of the landed repository from a plain clone. The co-owner peer path is additionally declared by the release-candidate contract: a distinct co-owner MCP bearer prepares an operational exact proposal, that same human's GitHub sign-in rules it, and a plain clone proves the Mainmind-member-attributed result. That is not a claim about the deployed Worker until the separately authorized live acceptance run passes and its exact version is promoted. Unclassified paths and operations outside the governed contract still fail closed rather than being approximated.

Two consequences you will meet in the reference:

• Knowledge scopes are enforced from the active member record before each MCP call. A missing or unknown document classification fails closed. The similarly named scopes field on a run remains descriptive work context; it is not a lock manager.
• proposal_ref on run_finish, and the diff, branch, base_sha, repo and pr_number fields on POST /api/asks, belong to the proposal path. They are stored and passed through to the decision page. Mainmind uses a short-lived GitHub App installation token to open the proposal, and can integrate only the exact proposal SHA the authenticated Owner or in-scope co-owner approved. The human and their agent never receive that token.

Optional tasks and automatic provider receipts

MCP list_provider_connections, call_provider, and issue_tool_permit accept an omitted run_id. Mainmind then creates an independent operation carrier; no start or finish call is needed. To attach a call_provider write to work you already started with run_start, pass that task's run_id and control_key. You may still pass operation_key so a retry recovers without sending again. MCP knowledge reads likewise require no run lifecycle. install_provider_connection is a control-plane write with no run: with a credential it stores the account encrypted and returns field names only; without one it writes the account pending and returns the placement link described above. The profile must name schema mainmind.connection-profile/v1, a lowercase id, and driver api-key/v1, sign-in/v1 or oauth2-refresh/v1. alias is kebab-case (google-ads); underscores are refused. slots are unique strings matching ^[A-Z][A-Z0-9_]{0,63}$, not {name} objects. A refusal names the failing field and the accepted shape (profile.schema must be …, profile.driver must be api-key/v1, sign-in/v1 or oauth2-refresh/v1, profile.api_origin must be an https origin only, credential is missing api_key, profile.slots[2] must be a string matching …, not an object with a name key, alias uses underscores; the accepted grammar is kebab-case, credential is missing slot X, credential has an extra key K). Install refusals point at the install tool page and never echo credential values. HTTP POST /api/tool-connections is that install contract. Replacement names expected_credential_generation when the generation is missing or stale; HTTP PUT /api/tool-connections is that replace contract and points at the replacement tool page. These are MCP contracts, not new HTTP provider routes.

Copy this Google Ads shape, substituting your alias. It has no credential, so an owner or co-owner finishes it on the placement page. Do not put values in the space's knowledge.

{
  "alias": "google-ads",
  "profile": {
    "schema": "mainmind.connection-profile/v1",
    "id": "google-ads",
    "driver": "oauth2-refresh/v1",
    "token_url": "https://oauth2.googleapis.com/token",
    "api_origin": "https://googleads.googleapis.com",
    "api_root": "/",
    "request_headers": ["content-type"],
    "response_headers": ["content-type"],
    "slots": ["GOOGLE_ADS_DEVELOPER_TOKEN"],
    "header_slots": { "developer-token": "GOOGLE_ADS_DEVELOPER_TOKEN" },
    "lease_env": {
      "base_url": "GOOGLE_ADS_BASE_URL",
      "ticket": "GOOGLE_ADS_ACCESS_TOKEN",
      "sentinels": ["GOOGLE_ADS_DEVELOPER_TOKEN"]
    }
  }
}

Then call issue_tool_permit. The returned commands.environment sets GOOGLE_ADS_BASE_URL to this account's gateway address, GOOGLE_ADS_ACCESS_TOKEN to the permit, and GOOGLE_ADS_DEVELOPER_TOKEN to placeholder text. Mainmind adds the access token and the developer token to each call; no value reaches the permit. The install receipt returns field names only.

An explicit task created by MCP run_start returns a private control_key. Its run_id is only a locator. Mutating or finishing that task needs both the current owning member and the key; an HTTP bearer cannot bypass that check. Existing legacy runs retain their member checks, and MCP control additionally requires the original session. Task receipts never return the key.

For a direct provider write, choose an operation_key before the call. Repeating that key returns recovery_only: true and the prior receipt locator without repeating the provider request, including after a timeout and when the retry reconstructs headers or body. Do not mint a new key to recover: that can send a second write. Recovery does not claim the operation succeeded. Read run_receipt and reconcile the actual provider object. An unresolved claim is never reclaimed automatically, even when its receipt contains no provider attempt yet.