Paragraph Authentication

generated: '2026-08-13'
method: searched
source: https://paragraph.com/auth.md
docs: https://docs.paragraph.com/developers
also_derived_from:
  - openapi/_original/paragraph-openapi-original.json
  - https://paragraph.com/.well-known/oauth-authorization-server
  - https://paragraph.com/.well-known/oauth-protected-resource
  - https://mcp.paragraph.com/.well-known/oauth-authorization-server
summary:
  types:
    - http
  primary: HTTP Bearer API key
  fine_grained: false
  provider_statement: >-
    "Paragraph API keys grant read and write access to the publication the user selects during
    approval. The keys are not currently fine-grained." — https://paragraph.com/auth.md
schemes:
  - name: apiKey
    type: http
    scheme: bearer
    description: >-
      API key for authenticating protected endpoints. Pass as Bearer token in the Authorization
      header. Applied to the write and account-scoped operations; public reads (search, feed,
      public publication/post fetch) need no credential.
    key_source: app.paragraph.com → Settings → API keys
    transport: 'Authorization: Bearer <api-key>'
    sources:
      - openapi/_original/paragraph-openapi-original.json
      - openapi/paragraph-analytics-api-openapi.yml
      - openapi/paragraph-auth-api-openapi.yml
      - openapi/paragraph-coins-api-openapi.yml
      - openapi/paragraph-discover-api-openapi.yml
      - openapi/paragraph-emails-api-openapi.yml
      - openapi/paragraph-me-api-openapi.yml
      - openapi/paragraph-posts-api-openapi.yml
      - openapi/paragraph-publications-api-openapi.yml
      - openapi/paragraph-subscribers-api-openapi.yml
      - openapi/paragraph-users-api-openapi.yml
discovery:
  protected_resource_metadata:
    url: https://paragraph.com/.well-known/oauth-protected-resource
    status: 200
    file: well-known/paragraph-oauth-protected-resource.json
    spec: RFC 9728
  authorization_server_metadata:
    url: https://paragraph.com/.well-known/oauth-authorization-server
    status: 200
    file: well-known/paragraph-oauth-authorization-server.json
    spec: RFC 8414
  scopes_supported: [api.read, api.write]
  note: >-
    New since the 2026-07-20 round. Paragraph now advertises its API resource through standard
    OAuth discovery documents even though the credential it ultimately issues is an API key
    rather than an OAuth access token.
agent_registration:
  published_skill: https://paragraph.com/auth.md
  saved_as: skills/paragraph-auth-SKILL.md
  model: anonymous registration followed by a human claim
  steps:
    - step: discover
      detail: Read the RFC 9728 / RFC 8414 documents at paragraph.com.
    - step: register
      detail: >-
        POST https://public.api.paragraph.com/api/v1/api/auth/sessions with an optional deviceName
        (and optional callbackUrl); receives sessionId, verificationUrl and expiresAt.
      operationId: createAuthSession
    - step: claim
      detail: >-
        Present verificationUrl (https://paragraph.com/api/auth?session=<session-id>) to the user,
        who signs in, selects a publication, and approves access. The agent must not attempt to
        approve on the user's behalf.
      operationId: getAuthSession
    - step: use
      detail: Send the issued API key as an Authorization Bearer header on subsequent calls.
  identity_types_supported: [anonymous]
  credential_types_supported: [api_key]
  agent_guardrails:
    - Do not try to approve the request for the user.
    - Do not expose the returned credential in logs, messages, or source code.
  assessment: >-
    A genuinely agent-native auth design: a machine-readable discovery document points at a
    markdown instruction file written for an agent, and the registration/claim handshake is
    modelled as three real REST operations with a human approval step in the middle.
mcp_authorization:
  issuer: https://mcp.paragraph.com
  model: OAuth 2.1 authorization code + PKCE, with RFC 7591 dynamic client registration
  scopes_supported: []
  browser_flow: true
  local_alternative: PARAGRAPH_API_KEY environment variable for the stdio server
  note: >-
    A separate authorization server from the REST resource, advertising no scopes — an MCP grant
    is coarser than the api.read/api.write split offered on the REST side.
not_supported:
  oauth2_in_spec: >-
    The OpenAPI declares no oauth2 securityScheme, so no scopes can be derived from the contract
    itself; they exist only in the discovery documents. See scopes/paragraph-scopes.yml.
  openid_connect: /.well-known/openid-configuration returns 404 on every host.
  mtls: not offered
  http_message_signatures: not offered
cross_ref:
  - scopes/paragraph-scopes.yml
  - well-known/paragraph-well-known.yml
  - conventions/paragraph-conventions.yml