Paragraph auth API

openapi: 3.1.0
info:
  title: Paragraph analytics auth API
  version: 1.0.0
  description: 'Public API for interacting with Paragraph publications, posts, users, and coined writing.


    ## Rate Limiting

    API requests are rate-limited to ensure fair usage. Contact support@paragraph.com for higher limits.


    ## Pagination

    List endpoints support cursor-based pagination using `cursor` and `limit` parameters.'
  contact:
    name: Paragraph Support
    email: support@paragraph.com
    url: https://paragraph.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://public.api.paragraph.com/api
  description: Production server
security:
- {}
tags:
- name: auth
paths:
  /v1/api/auth/sessions:
    post:
      description: Creates a new browser-based auth session for CLI or other API clients. The returned verification URL should be opened in the user's browser to complete authentication.
      summary: Create an API auth session
      tags:
      - auth
      parameters: []
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties:
                deviceName:
                  type: string
                  maxLength: 100
                  description: Name of the device requesting access (e.g. user@MacBook-Pro.local)
                callbackUrl:
                  type: string
                  format: uri
                  maxLength: 2048
                  description: HTTPS callback URL to redirect the user to after approving the session
      responses:
        '201':
          description: Session created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    description: Unique session identifier
                  verificationUrl:
                    type: string
                    description: URL to open in the browser to approve the session
                  expiresAt:
                    type: string
                    description: ISO 8601 timestamp when the session expires
                required:
                - sessionId
                - verificationUrl
                - expiresAt
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                    description: Always false for error responses
                  msg:
                    type: string
                    description: Human-readable error message
                required:
                - success
                - msg
      operationId: createAuthSession
  /v1/api/auth/sessions/{sessionId}:
    get:
      description: Poll the status of an auth session. Returns the API key once the session has been approved in the browser.
      summary: Poll an API auth session
      tags:
      - auth
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
        description: Session ID returned from create
      responses:
        '200':
          description: Current session status
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    status:
                      type: string
                      enum:
                      - pending
                    deviceName:
                      type: string
                    callbackUrl:
                      type: string
                  required:
                  - status
                  - deviceName
                - type: object
                  properties:
                    status:
                      type: string
                      enum:
                      - completed
                    apiKey:
                      type: string
                  required:
                  - status
                  - apiKey
                - type: object
                  properties:
                    status:
                      type: string
                      enum:
                      - expired
                  required:
                  - status
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                    description: Always false for error responses
                  msg:
                    type: string
                    description: Human-readable error message
                required:
                - success
                - msg
      operationId: getAuthSession
    delete:
      description: Cancels a pending auth session. Only pending sessions can be denied.
      summary: Deny an API auth session
      tags:
      - auth
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
        description: Session ID to deny
      responses:
        '200':
          description: Session denied successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                required:
                - success
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                    description: Always false for error responses
                  msg:
                    type: string
                    description: Human-readable error message
                required:
                - success
                - msg
      operationId: deleteAuthSession
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: API key for authenticating protected endpoints. Pass as Bearer token in Authorization header.
x-mint:
  mcp:
    enabled: true