Skip to main content

Authentication

The Massdriver GraphQL API uses service account tokens for authentication. All requests must include valid credentials in the Authorization header.

Getting a Service Account Token​

  1. Log in to the Massdriver Console
  2. Navigate to Organization Settings → Service Accounts
  3. Create a new service account and copy the token
  4. Note your organization identifier (slug) from the URL or settings

Making Authenticated Requests​

Use HTTP Basic authentication with your organization identifier as the username and service account token as the password:

# Encode credentials: org_identifier:service_account_token
CREDENTIALS=$(echo -n "your-org-id:your-service-account-token" | base64)

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

One-liner​

curl -X POST https://api.massdriver.cloud/api/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'your-org-id:your-token' | base64)" \
  -d '{"query": "{ server { mode version } }"}'

GraphQL Clients​

JavaScript/TypeScript​

import { GraphQLClient } from 'graphql-request';

const orgId = process.env.MASSDRIVER_ORG_ID;
const token = process.env.MASSDRIVER_API_TOKEN;
const credentials = Buffer.from(`${orgId}:${token}`).toString('base64');

const client = new GraphQLClient('https://api.massdriver.cloud/api/v1', {
  headers: {
    Authorization: `Basic ${credentials}`,
  },
});

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

Python​

import requests
import base64

org_id = "your-org-id"
token = "your-service-account-token"
credentials = base64.b64encode(f"{org_id}:{token}".encode()).decode()

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Basic {credentials}"
}

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

Error Responses​

Unauthenticated​

If credentials are missing or invalid:

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

Forbidden​

If the service account doesn't have permission for the requested resource:

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

Viewer Query​

Use the viewer query to verify your authentication and see the current service account:

query {
  viewer {
    ... on ServiceAccountViewer {
      name
      organization {
        id
        name
      }
    }
  }
}

Deprecated: x-md-api-key Header​

The x-md-api-key header is deprecated and will be removed in a future version. Migrate to Basic authentication as shown above.