Authentication and tokens

Masthead provides several programmatic interfaces, each requiring a specific authentication method:

• BigQuery shared dataset: Authenticates using your Google Cloud IAM credentials. For details, see the BigQuery shared dataset setup guide.
• Resource management API: Authenticates using static API tokens for the Masthead Terraform provider. For details, see the Resource management API configuration guide.
• MCP server: Authenticates using Google SSO for interactive users or service account token exchanges for headless environments.

---

MCP server

The Masthead MCP server supports two authentication modes depending on your environment.

Interactive user accounts

If you use interactive developer tools like Claude Code, Codex, or Google Antigravity on your local workstation, the client automatically handles authentication:

1. On first launch, the client opens a browser tab.
2. Log in using your Google SSO credentials.
3. The client caches the returned JWT locally for subsequent requests.

Headless service accounts

If you run MCP clients in headless environments like Google Cloud Build, GitHub Actions, or background daemon processes, you must exchange a Google Cloud service account token for a Masthead access token.

Register the service account

Create a service account in your Google Cloud project and register its email address with your Masthead tenant.

Exchange tokens

Exchange your service account’s Google ID token for a Masthead access token. The returned token is valid for 1 hour.

Bash / CLI

To exchange the token using the Google Cloud CLI and curl, run the following commands:

# 1. Mint Google ID token (--include-email is required)
IDT=$(gcloud auth print-identity-token \
  --impersonate-service-account="your-bot@YOUR_PROJECT.iam.gserviceaccount.com" \
  --audiences=https://sso.mastheadata.com \
  --include-email)

# 2. Exchange for Masthead Access Token
TOKEN=$(curl -s -X POST https://sso.mastheadata.com/oauth2/token \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  -d 'subject_token_type=urn:ietf:params:oauth:token-type:id_token' \
  -d 'client_id=service-account' \
  --data-urlencode "subject_token=$IDT" | jq -r .access_token)

Python

To exchange the token programmatically in a Python environment, use the following code:

import google.auth
from google.auth import impersonated_credentials
from google.auth.transport.requests import Request
import requests

# Target audience and service account
AUDIENCE = "https://sso.mastheadata.com"
SERVICE_ACCOUNT_EMAIL = "your-bot@YOUR_PROJECT.iam.gserviceaccount.com"

# 1. Mint the Google ID token (impersonating the service account)
source_credentials, _ = google.auth.default()
target_credentials = impersonated_credentials.IDTokenCredentials(
    source_credentials,
    target_audience=AUDIENCE,
    target_service_account=SERVICE_ACCOUNT_EMAIL,
    include_email=True
)
target_credentials.refresh(Request())
id_token = target_credentials.token

# 2. Exchange the Google ID token for a Masthead access token
response = requests.post(
    "https://sso.mastheadata.com/oauth2/token",
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
        "client_id": "service-account",
        "subject_token": id_token,
    }
)
response.raise_for_status()
token = response.json()["access_token"]

Configure the client

Pass the returned token in the static Authorization header of your client configuration. For example, to add the server in Claude Code:

claude mcp add --transport http masthead https://mcp.mastheadata.com/mcp \
  --header "Authorization:Bearer $TOKEN"