> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Mammoth API authentication

> Authenticate against the Mammoth API with an API token sent as a Bearer header. Base URL, credential storage, and how to sign in without a terminal.

Scripts, the REST API and the SDK use an API token, sent as `Authorization: Bearer mm_...`. MCP clients, the CLI's browser and device sign-in, and apps you register for Sign in with Mammoth use OAuth instead. Browser sessions use JWTs, which are not available to an integration.

## Which credential for which surface

| You are using | Credential | How you get it |
| --- | --- | --- |
| REST API, `mammoth-io` SDK, scripts and CI | `mm_` API token, sent as a Bearer header | **Settings → API Keys → Generate key**, described below |
| The `mammoth` CLI, on your own machine | A browser sign-in, or a device code on a machine with no browser | `mammoth auth login --method oauth`, or `mammoth auth login --method device` |
| The CLI in CI or any unattended run | The same `mm_` API token | `MAMMOTH_API_TOKEN` in the environment, or `mammoth auth login --input creds.json` |
| The CLI driven by a coding agent | A device code you approve | The agent runs `mammoth auth login --device` and shows you the link and code |
| The Mammoth MCP server, `https://mcp.mammoth.io/mcp` | OAuth, through your MCP client | The client opens a Mammoth consent page. See [Mammoth MCP server](https://mammoth.io/docs/agents/mcp/) |
| Your own app, acting as the people who use it | OAuth, with an app you register | **Settings → API Keys → OAuth apps → Register app**, described in [Sign in with Mammoth for your own app](#sign-in-with-mammoth-for-your-own-app) |

A token made by hand in Settings does not work against the MCP server: the server accepts only tokens issued by the OAuth sign-in.

The full REST reference is the OpenAPI 3.1 document at `https://app.mammoth.io/api/v2/docs/openapi.json`. It needs credentials: without them it answers 401. Open it in a browser where you are signed in to the web app, or fetch it with your token:

```bash
curl -sS https://app.mammoth.io/api/v2/docs/openapi.json \
  -H "Authorization: Bearer $MAMMOTH_API_TOKEN" -o openapi.json
```

> **Keep credentials out of your code**
>
> Keep the token in an environment variable, `MAMMOTH_API_TOKEN`: never in a prompt, a script, or a file in the repository. The SDK gets it because you pass it in; curl gets it from the header you write; the CLI reads the variable by itself.

## Sign in to the CLI without a token

`mammoth auth login` asks how to sign in, or you pass the method:

| Command | What happens |
| --- | --- |
| `mammoth auth login --method oauth` | Opens your browser to Mammoth's consent page. The CLI stores a short-lived token and refreshes it for you. `--no-browser` prints the sign-in URL instead of opening it. |
| `mammoth auth login --method device` (or `--device`) | For a machine with no browser. The CLI prints a short code and a URL; you approve on any other device and the CLI waits. |
| `mammoth auth login --method token` | Prompts for an `mm_` API token with hidden input. |

`mammoth auth logout` signs out. For a browser or device sign-in it also revokes that connection on the server.

OAuth access tokens last one hour, and the CLI refreshes them for you. Refresh tokens rotate on every use and have no expiry of their own. See [how long sign-in lasts](https://mammoth.io/docs/agents/mcp/#how-long-sign-in-lasts) for the details.

### Approve a device sign-in

`mammoth auth login --device` prints a link and a code of eight letters, such as `BCDF-GHJK`. The code uses no vowels and no look-alike characters. Open the link on any device where you can sign in to Mammoth:

1. The page **Sign in to the Mammoth CLI** asks you to "Enter the code your terminal is showing." The link the CLI prints already fills the **Code** box. Click **Continue**.
2. The page shows "Mammoth CLI wants to sign in with code BCDF-GHJK." and the email you are signed in with. Check that the code matches your terminal. **Change code** goes back a step.
3. Pick the workspace and the projects the CLI may use, as on the consent page below.
4. Click **Approve**, or **Deny** to refuse.

The page then says **CLI signed in** or **Sign-in denied**, with "You can return to your terminal." The CLI checks every 5 seconds and finishes on its own.

A code expires after 15 minutes and works once. An expired, used or mistyped code shows "This code is not valid, has expired or was already used. Start the sign-in again from the CLI." Only the Mammoth CLI can use device sign-in. Other apps use the browser flow.

## Connected apps and revoking access

When you sign in to an MCP client or to the CLI with OAuth, Mammoth shows a consent page titled, for example, **Allow Claude to access Mammoth Analytics**. On it you:

| Option | What it does |
| --- | --- |
| Workspace | The one workspace the app works in. An app registered in a workspace always gets that workspace. |
| Projects (**Select projects**) | One or more projects, or **All projects** "(existing and new ones)". |
| **Read-only: let it look at your data, never change it** | Limits the app to reading. |
| **Switch account** | Signs you in as someone else first. |
| **Allow** / **Cancel** | Approves, or sends you back to the app with nothing granted. |

The page says what the app may do: "Read and change data in the project you choose as you, the same as an API token." and "It cannot read data in your other workspaces." With **Read-only** it says the app can read and "cannot change anything". A read-only connection is refused on every write, whether it goes through the MCP server or straight to the REST API: the API answers 403 with `error_code` `4GENR034`, "This connection is read-only: it can read data but not change it".

If you are not a member of the workspace an app is registered in, the page says so and asks you to get an invite or switch account. If you already connected the app, the page reconnects it without asking again.

Each app keeps at most 10 sign-ins. An 11th signs out the one used least recently.

To remove access, open **Settings → Connected apps** in the web app and choose **Revoke** next to the app. It loses access at once, including for anything it is doing at that moment. You can connect it again from the app.

## Sign in with Mammoth for your own app

To let people connect their Mammoth account to an app you build, register the app as an OAuth app. Mammoth is then the authorization server, and your app gets a token that acts as the person who approved it.

### Register the app

1. Go to **Settings → API Keys**. In the **OAuth apps** card, click **Register app**.
2. In **Register OAuth app**, fill in the fields below and confirm.
3. Under **Save these now**, copy the **Client ID** and, for a confidential app, the **Client secret**. "The secret is shown only once. Store it securely."

| Field | What it does |
| --- | --- |
| **Name** | Shown on the consent page. Up to 100 characters. |
| **Redirect URIs** | Where Mammoth sends the person back, 1 to 10 URIs. Each must be an absolute `https://` URL, or a loopback `http://localhost`, `http://127.0.0.1` or `http://[::1]` URL, with no `#`, spaces, backslashes or `*`. |
| **Public app** | "No client secret. For desktop apps and CLIs." For a public app, a listed loopback URI matches on any port. |
| **Optional details** | **Description**, **Logo URL**, **Terms of service URL** and **Privacy policy URL**. The consent page shows the logo and links. |

Only someone whose role can rename the workspace can register or delete OAuth apps (the Workspace Owner, unless a custom role grants it). Others see "You can't register or delete OAuth apps in this workspace. Contact the Workspace Owner." Deleting an app ends every connection people made to it.

### Endpoints

| | URL |
| --- | --- |
| Issuer | `https://app.mammoth.io/api/v2` |
| Metadata (RFC 8414) | `https://app.mammoth.io/.well-known/oauth-authorization-server/api/v2` |
| Authorize | `https://app.mammoth.io/api/v2/oauth/authorize` |
| Token | `https://app.mammoth.io/api/v2/oauth/token` |

Mammoth supports the authorization code grant with PKCE `S256` and the refresh token grant. There are no scopes to request: the person picks the workspace, projects and **Read-only** on the consent page.

### Send the person to the authorize URL

| Parameter | Value |
| --- | --- |
| `response_type` | `code` |
| `client_id` | Your app's client ID |
| `redirect_uri` | Exactly one of the registered redirect URIs |
| `code_challenge` | The base64url SHA-256 of your code verifier, 43 characters |
| `code_challenge_method` | `S256` (the only method) |
| `state` | Optional, up to 2,048 characters, returned to you unchanged |

After **Allow**, Mammoth redirects to your `redirect_uri` with `code`, your `state` and `iss`. After **Cancel**, it redirects with `error=access_denied`. The code lasts 60 seconds and works once.

### Exchange the code for tokens

POST a form (`application/x-www-form-urlencoded`) to the token endpoint:

```bash
curl -sS https://app.mammoth.io/api/v2/oauth/token \
  -u "<client_id>:<client_secret>" \
  -d grant_type=authorization_code \
  -d code="<code>" \
  -d redirect_uri="https://app.example.com/oauth/callback" \
  -d code_verifier="<code_verifier>"
```

A confidential app authenticates with HTTP Basic, as above, or with `client_id` and `client_secret` form fields. A public app sends `client_id` only and no secret. The code verifier must be 43 to 128 characters.

The response:

| Field | Meaning |
| --- | --- |
| `access_token` | An `mm_` token. Send it as `Authorization: Bearer mm_...`, the same as an API token. |
| `token_type` | `Bearer` |
| `expires_in` | `3600` seconds |
| `refresh_token` | Use it once to get new tokens |
| `workspace_id` | The workspace the token works in |
| `project_id`, `project_ids` | `project_ids` lists the chosen projects and `project_id` is the lowest of them. Both are `null` for all projects. |

To refresh, POST `grant_type=refresh_token` and `refresh_token`, with the same client authentication. Each refresh returns a new refresh token and the old one stops working, as described in [how long sign-in lasts](https://mammoth.io/docs/agents/mcp/#how-long-sign-in-lasts).

Errors follow RFC 6749: a JSON body with `error` and `error_description`. A wrong client secret returns 401 `invalid_client`. A used or expired code returns `invalid_grant` with "The authorization code is invalid, expired or used", and a verifier that does not match returns "code_verifier does not match the code_challenge".

## Get your credentials

You need one value: an **API token**.

1. Open the Mammoth web app.
2. Go to **Settings → API Keys**. In the **API tokens** card, choose **Generate key**.
3. In **Create API key**, enter a name, optionally turn on **Project scoped** and pick a project, then choose **Create key**.
4. In **API key created**, choose **Copy secret**: the token starts with `mm_` and is shown once. "After this dialog closes, the secret is gone." If you lose it, create a new one.

Creating tokens needs a role that can manage API tokens. Without it, the page shows only "You can't view or manage API keys in this workspace. Contact the Workspace Owner." [Workspace settings](https://mammoth.io/docs/learn/workspace/api-keys/) describes every card on the page, including **Connect an AI assistant** and **Use the Mammoth CLI**.

A token works only in the workspace and on the server where you created it, and it names that workspace itself. Neither the SDK nor the CLI asks you for a workspace id. You need the id only to write a REST URL such as `/workspaces/<workspace_id>/projects`: it is the number after `/workspaces/` in the web app's address bar.

> **Project-limited tokens**
>
> A token can be limited to one project when you create it. It then gets HTTP 403 in every other project, including a project it created. Create the token without a project if your code creates or switches projects.

> **API access works the same on every plan**
>
> A token behaves identically regardless of which plan you're on. What changes with the plan is what sits behind the token: storage, how many builders you have, and how often data refreshes. A workspace with a token has the same limits it has in the browser.

## Base URL

```
https://app.mammoth.io/api/v2
```

`app` is the default server prefix and names your region. If your Mammoth runs on a different prefix, substitute it: `https://<prefix>.mammoth.io/api/v2`.

## Headers

Every request carries one header.

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer mm_...`, your API token |

A token belongs to one workspace, so you don't send a workspace header with it. If a request does name a workspace (an `X-WORKSPACE-ID` header, or the workspace id in the URL path), it must be the token's own workspace, or the API returns 401. Only the deprecated key and secret headers require `X-WORKSPACE-ID`.

> **X-API-KEY and X-API-SECRET are deprecated**
>
> The API still accepts the older key and secret headers, but new tokens have no secret. Use the Bearer token for anything new.


**curl**

```bash
curl https://app.mammoth.io/api/v2/workspaces/$MAMMOTH_WORKSPACE_ID/projects \
  -H "Authorization: Bearer $MAMMOTH_API_TOKEN"
```

**mammoth-io**

```python
import asyncio
import os

from mammoth import MammothClient


async def main():
    async with MammothClient(
        api_token=os.environ["MAMMOTH_API_TOKEN"],
    ) as client:
        client.set_project_id(10)
        await client.projects.list()


asyncio.run(main())
```

**CLI**

```bash
mammoth auth login            # asks how to sign in: browser, device code or token

# No terminal (CI): the CLI reads the token from the environment
export MAMMOTH_API_TOKEN="mm_<your-token>"
mammoth doctor --output json --no-input
```


The SDK and the CLI add this header for you. The SDK is async (see [Python SDK](https://mammoth.io/docs/build/sdk/)). It needs only the token, because a token names its own workspace. `workspace_id` is optional with a token: it is a hint that saves one lookup, the SDK does not check it, and a wrong one makes requests fail on the server. Most operations also need a project; set it with `client.set_project_id(…)`.

## Keep credentials out of your code

Use environment variables. Never hard-code a token, never put one in a prompt, and never commit one.

```bash
export MAMMOTH_API_TOKEN="mm_<your-token>"
export MAMMOTH_WORKSPACE_ID="<your-workspace-id>"   # only for REST URLs, as in the curl example
```

### The CLI in CI

A CI job cannot answer a hidden prompt. The simplest route is the environment variable: when `MAMMOTH_API_TOKEN` is set, the CLI uses it for every command, and `MAMMOTH_SERVER_PREFIX` picks a region other than `app`. Store the token in your CI secret store and expose it as that variable.

```bash
mammoth doctor --output json --no-input
```

The alternative is to save a profile once from an owner-only file outside the repository:

**`creds.json`**

```json
{
  "api_token": "mm_<your-token>",
  "server_prefix": "app"
}
```

`api_token` is required. `server_prefix` is optional and defaults to `app`. The file takes no other field; a `workspace_id` in it is rejected.

Create the file owner-only (`0600`) from the start, for example from your CI secret store; don't write it first and `chmod` it afterwards, because another process may already have read it. The CLI refuses a group- or world-readable file.

```bash
mammoth auth login --input creds.json --storage file --output json --no-input
```

`--storage file` is explicit because `--storage auto`, the default, picks the OS keyring and fails in a process that has none. To target a different region, pass `--server-prefix LABEL`. Delete the file once the credentials are stored.

> **The environment variable outranks your saved profile**
>
> While `MAMMOTH_API_TOKEN` is set, the CLI uses it instead of the profile you saved with `mammoth auth login`, and prints one line on stderr saying so. Name a profile with `--profile NAME` or `MAMMOTH_PROFILE` to use it anyway, or unset the variable. The SDK never reads the variable by itself: you pass it to the client.

## Finding ids from a URL

The SDK can pull ids straight out of an app URL.

```python
from mammoth import parse_path

ids = parse_path("https://app.mammoth.io/#/workspaces/11/projects/10/views/1039")
# {"workspace_id": 11, "project_id": 10, "dataview_id": 1039}
```

## When authentication fails

A bad or missing credential returns **HTTP 401** with this body:

```json
{
  "error_code": "4RESO003",
  "name": "AUTHENTICATION_ERROR",
  "message": "Invalid token",
  "details": {"error_object": {"code": 12, "message": "Token is invalid"}, "status_code": 401}
}
```

Branch on `error_code`, not on `message`. The SDK raises `MammothAuthError`; the CLI exits with code **4**. [Errors](https://mammoth.io/docs/build/errors/) has the error body in full.

> **Not retryable**
>
> Neither is worth retrying. Re-check the token instead. A project-limited token gets HTTP 403, not 401, outside its project. The CLI shows such a token only its own project: `project list` lists that one project, and `project get OTHER_ID` is refused locally with `authorization_required`. The only CLI exit code worth a retry is `7`.

## Next up

- [Quickstart](https://mammoth.io/docs/build/quickstart/): your first real call, three ways.
- [Command contract](https://mammoth.io/docs/build/): everything you can do, with its blast radius.

---
Source: https://mammoth.io/docs/build/auth.md · Updated: 2026-11-02
