Groundmail Dev Authentication

generated: '2026-10-30'
method: searched
generator: extract-docs-artifacts.py (local)
source: https://docs.groundmail.dev/authentication
sources:
- https://docs.groundmail.dev/authentication
- https://docs.groundmail.dev/authentication/azure-managed-identity
- https://docs.groundmail.dev/api-keys
- https://docs.groundmail.dev/guides/better-auth
description: Authentication methods documented for Groundmail API
schemes:
- type: http-bearer
  name: API key
  evidence: 'Groundmail authenticates API requests with a Bearer credential: an API key ( gm_… ) for servers and CI, a short-lived OAuth access
    token ( gm_oat_… ) for the CLI and agents, or, from Azure, a managed identity token with no key at all.'
  location: header
  header: Authorization
  how_to_obtain: Create in the dashboard → API Keys → Create and copy the secret (shown once).
- type: http-bearer
  name: Azure managed identity token
  evidence: 'Workloads on Azure (Container Apps, App Service, Functions, AKS workload identity, VMs) can authenticate with their managed identity
    instead of a key: the app gets a short-lived Microsoft Entra access token from Azure and sends it as Authorization: Bearer <token> .'
  location: header
  header: Authorization
  how_to_obtain: Configure a managed identity in Azure, then use DefaultAzureCredential with the scope https://api.groundmail.dev/.default to
    acquire a token.
- type: oauth2
  name: OAuth Device Authorization Grant
  evidence: 'Other tools can use the same flow, the OAuth 2.0 Device Authorization Grant (RFC 8628):'
  token_url: https://api.groundmail.dev/oauth/token
  scopes:
  - openid
  - email
  - emails:send
  - domains:read
  - etc.
  how_to_obtain: POST https://api.groundmail.dev/oauth/device_authorization with client_id and scope, then poll https://api.groundmail.dev/oauth/token.
- type: oauth2
  name: Authorization Code Flow (PKCE) for MCP clients
  evidence: 'The hosted MCP server signs clients in the same way, with the authorization code flow (PKCE): the person approving picks the scopes
    the client gets, and the connection appears under Settings → CLIs & agents with its scopes, where it can be revoked.'
  token_url: https://api.groundmail.dev/oauth/token
  authorize_url: https://app.groundmail.dev/.well-known/oauth-authorization-server
  how_to_obtain: Run groundmail login which opens the browser for the authorization code flow.
docs: https://docs.groundmail.dev/authentication