> For the complete documentation index, see [llms.txt](https://docs.themochi.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.themochi.app/start-here/authentication.md).

# Choose how to authenticate

**Authentication** is how Mochi confirms which integration is making a request. Choose one method based on where the integration runs.

| Where the integration runs                        | Use                          | Why                                                                                                                 |
| ------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| A server, scheduled job, or CI runner             | API key                      | It can read a secret from a server-side secret manager without a person signing in each time.                       |
| A trusted local computer with a person present    | Mochi CLI with OAuth         | A browser opens so the person can choose an organization and approve permissions. The CLI stores the result safely. |
| An AI tool already connected to Mochi through MCP | Existing MCP connection      | Keep the existing connection. Do not export or convert its credential.                                              |
| A third-party browser application                 | Registered OAuth application | The app redirects the user to Mochi for approval and never receives the user's password.                            |

If you are connecting an AI tool, follow [Connect an AI agent](/common-tasks/connect-ai-agent.md) after choosing the matching row.

## Use an API key on a server

Send the key in the `Authorization` header of every request:

```http
Authorization: Bearer mochi_sk_live_...
```

`Bearer` means that anyone who has the key can use it. Protect the key like a password.

## Keep an API key safe

* Mochi shows the plaintext key once at creation.
* Store it in a server-side secret manager.
* Never put it in frontend JavaScript, mobile applications, URLs, source control, documentation, or logs.
* Never send it in a query parameter.
* Use separate keys for separate integrations so each can be scoped and revoked independently.

Each key belongs to one Mochi organization. It cannot access another organization's resources. A request for a resource outside its organization returns `404` without revealing whether that resource exists.

## Use browser approval with the Mochi CLI

OAuth lets a person approve a connection in the browser without giving the integration a password. A CLI OAuth connection also belongs to one organization and has only the approved scopes. The CLI stores its credential outside prompts and command history. Do not read or copy that storage.

Already being signed in to Mochi makes approval faster, but it does not skip consent. The person still chooses the organization and permissions.

## Advanced: key identity types

Mochi may issue an **organization-principal key** to an approved server integration. This key represents the organization. A **member-bound key** also follows the member's current role and active status.

Connection and team-management changes require an organization-principal key. A member-bound key cannot perform those operations even when it has the named scope.

Confirm current authentication requirements for an exact endpoint in the [canonical OpenAPI contract](https://openapi.gitbook.com/o/bpgVa93BfrzaqXzuggv8/spec/mochi-api.json).

## Replace or revoke a key

Request a new key before replacing an existing key. Deploy the new key to your integration, verify it, and then ask Mochi to revoke the old key.

Stop using a key immediately if it may have appeared in logs, source control, screenshots, browser storage, or a support message. Contact Mochi to revoke it. Share only its non-secret name or prefix, never the full key.