Mammoth API authentication
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 |
| 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 |
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:
curl -sS https://app.mammoth.io/api/v2/docs/openapi.json \
-H "Authorization: Bearer $MAMMOTH_API_TOKEN" -o openapi.json
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 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:
- 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.
- 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.
- Pick the workspace and the projects the CLI may use, as on the consent page below.
- 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
- Go to Settings → API Keys. In the OAuth apps card, click Register app.
- In Register OAuth app, fill in the fields below and confirm.
- 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:
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.
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.
- Open the Mammoth web app.
- Go to Settings → API Keys. In the API tokens card, choose Generate key.
- In Create API key, enter a name, optionally turn on Project scoped and pick a project, then choose Create key.
- 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 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.
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.
curl
curl https://app.mammoth.io/api/v2/workspaces/$MAMMOTH_WORKSPACE_ID/projects \
-H "Authorization: Bearer $MAMMOTH_API_TOKEN"
mammoth-io
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
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). 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.
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.
mammoth doctor --output json --no-input
The alternative is to save a profile once from an owner-only file outside the repository:
creds.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.
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.
Finding ids from a URL
The SDK can pull ids straight out of an app URL.
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:
{
"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 has the error body in full.
Next up
- Quickstart: your first real call, three ways.
- Command contract: everything you can do, with its blast radius.