Crawlgraph Authentication

generated: '2026-08-13'
method: searched
source: https://crawlgraph.com/docs/api
also_derived_from: openapi/crawlgraph-v1-openapi.yml
note: >-
  The upstream OpenAPI (https://crawlgraph.com/api/v1/openapi.json) declares NO
  components.securitySchemes and no security requirement — a real gap, since every /api/v1/*
  route except free-key rejects an unauthenticated call with 401. The scheme below is taken from
  section 2 ("Authentication") of the published docs and confirmed by live probe: an anonymous
  GET https://crawlgraph.com/api/v1/releases returns 401. The refined spec in openapi/ adds the
  missing bearerAuth scheme; the fix is also expressed as an Overlay in overlays/.

summary:
  types: [http]
  oauth2: false
  openid_connect: false
  mutual_tls: false
  scopes: false

schemes:
  - name: bearerAuth
    type: http
    scheme: bearer
    in: header
    header: Authorization
    format: 'Bearer cg_live_<key>'
    key_prefix: cg_live_
    key_length: ~52 characters
    description: >-
      Every request to /api/v1/* needs a bearer token in the Authorization header. Keys are
      prefixed cg_live_ and are roughly 52 characters long.
    sources:
      - https://crawlgraph.com/docs/api
      - openapi/crawlgraph-v1-openapi.yml

key_management:
  self_service: true
  free_key_endpoint: POST /api/v1/free-key
  free_key_note: >-
    The one unauthenticated route. Takes an email address and mails a free-tier key (15 backlink
    calls/month). No card, no signup, one active key per email. The key is NEVER returned in the
    HTTP response — only by email.
  paid_key_console: https://crawlgraph.com/account
  max_active_keys: 10
  labels_supported: true
  shown_once: true
  recovery: none
  rotation: revoke and create a new key
  note: >-
    The full key is shown only once at creation; there is no recovery path. Up to 10 active keys
    per user, each labelable (e.g. "production", "n8n-bot").

tier_gating:
  - tier: free
    quota: 15 backlink calls / month
    tools: [backlinks, releases]
    note: Free keys can call backlinks. Gap analysis and outreach targets are rejected.
  - tier: lifetime
    price: $99 one-time
    quota: 1,000 backlink calls + 50 gap jobs / month
    tools: [backlinks, releases, gap_analysis, gap_outreach_targets]

failure_modes:
  - code: auth_missing
    status: 401
    meaning: Authorization header missing or malformed.
  - code: auth_invalid
    status: 401
    meaning: Key unknown, revoked, or owner refunded.

mcp:
  shares_credential: true
  env: CRAWLGRAPH_API_KEY
  note: >-
    The hosted MCP server at https://crawlgraph.com/mcp uses the same bearer key and the same
    quotas as the HTTP API. tools/list is answerable anonymously; tool invocation is not.

x-evidence:
  - {url: 'https://crawlgraph.com/api/v1/releases', status: 401, note: anonymous GET rejected}
  - {url: 'https://crawlgraph.com/api/v1/openapi.json', status: 200, note: spec served anonymously but declares no securitySchemes}
  - {url: 'https://crawlgraph.com/docs/api', status: 200, note: section 2 documents the bearer scheme and cg_live_ prefix}