Authentication

All Massdriver GraphQL API requests must include credentials in the Authorization header. The endpoint is:

https://api.massdriver.cloud/api/v2

The server accepts three authentication schemes, dispatched by the header value:

Scheme	Used for
Bearer md_…	Access tokens (recommended for API clients and CI)
Bearer mds_…	OAuth session tokens (issued by POST /oauth/token, mainly for first-party UI clients)
Basic <base64>	Terraform / OpenTofu state backend, using organization_identifier:service_account_secret

Access Tokens (Recommended)

Access tokens are issued in the Massdriver console and can be scoped to a user or a service account. They begin with the md_ prefix and are sent as a Bearer token.

curl -X POST https://api.massdriver.cloud/api/v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer md_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"query": "{ viewer { __typename ... on ServiceAccountViewer { name organization { id name } } } }"}'

To mint a service-account token:

1. Sign in to the Massdriver Console
2. Open Organization Settings → Service Accounts
3. Create a service account and generate an access token
4. Copy the token (it is shown only once)

GraphQL Clients

JavaScript / TypeScript

import { GraphQLClient } from 'graphql-request';

const client = new GraphQLClient('https://api.massdriver.cloud/api/v2', {
  headers: {
    Authorization: `Bearer ${process.env.MASSDRIVER_ACCESS_TOKEN}`,
  },
});

const data = await client.request(query, variables);

Python

import os
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['MASSDRIVER_ACCESS_TOKEN']}",
}

response = requests.post(
    "https://api.massdriver.cloud/api/v2",
    json={"query": query, "variables": variables},
    headers=headers,
)

Basic Authentication (Terraform / OpenTofu State)

Basic authentication is used by the Massdriver Terraform/OpenTofu state backend. The username is the organization's identifier (the short, hyphenated handle shown in the console URL); the password is a service account secret.

CREDENTIALS=$(echo -n "your-org-identifier:your-service-account-secret" | base64)

curl -X POST https://api.massdriver.cloud/api/v2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $CREDENTIALS" \
  -d '{"query": "{ viewer { __typename } }"}'

For general-purpose GraphQL access, prefer Bearer access tokens.

Verifying Your Credentials

Use the viewer query to confirm authentication and inspect the active subject:

query {
  viewer {
    __typename
    ... on AccountViewer {
      id
      email
    }
    ... on ServiceAccountViewer {
      id
      name
      organization {
        id
        name
      }
    }
  }
}

Error Responses

Unauthenticated

Returned when credentials are missing or invalid.

{
  "errors": [{
    "message": "Authentication required",
    "extensions": { "code": "UNAUTHENTICATED" }
  }]
}

Forbidden

Returned when the authenticated subject lacks the required ABAC permission for the operation. See the GraphQL permissions reference for the operation-to-permission mapping.

{
  "errors": [{
    "message": "You do not have permission to view this environment",
    "extensions": { "code": "FORBIDDEN" }
  }]
}