Commentary Authentication API

The Authentication API from Commentary — 6 operation(s) for authentication.

GitHub OpenAPI

Operations 7

2 of 7 operations are conformant: apis.io called them with no credentials and the responses matched this contract. Checked 2026-11-12. how this works · status file

GET /.well-known/oauth-authorization-server Get OAuth authorization server metadata conformant #
GET /.well-known/oauth-protected-resource Get OAuth protected resource metadata conformant #
POST /oauth/register Register a public OAuth client #
GET /oauth/authorize Show the OAuth authorization page #
POST /oauth/authorize Approve an OAuth authorization request #
POST /oauth/device/code Start OAuth device authorization #
POST /oauth/token Exchange OAuth authorization code, device code, or refresh token #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/commentary-dev:commentary-dev-authentication-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

commentary-dev-authentication-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Commentary Dev Authentication API
  version: 0.1.0
  x-commentary-api-version: v1
  x-commentary-compatibility-policy: /docs/api/versioning.md
  x-commentary-feature-key: api.openapi_docs
  description: 'Operations tagged Authentication across 2 of this provider''s published API definitions: commentary-dev-openapi.json, commentary-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://commentary.dev
  description: Configured Commentary origin.
- url: http://localhost:3000
  description: Local development.
tags:
- name: Authentication
paths:
  /.well-known/oauth-authorization-server:
    get:
      operationId: getOAuthAuthorizationServerMetadata
      tags:
      - Authentication
      summary: Get OAuth authorization server metadata
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer:
                    type: string
                    format: uri
                  authorization_endpoint:
                    type: string
                    format: uri
                  token_endpoint:
                    type: string
                    format: uri
                  registration_endpoint:
                    type: string
                    format: uri
                  device_authorization_endpoint:
                    type: string
                    format: uri
                  scopes_supported:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalScope'
                additionalProperties: true
    servers:
    - url: https://commentary.dev
      description: Configured Commentary origin.
    - url: http://localhost:3000
      description: Local development.
  /.well-known/oauth-protected-resource:
    get:
      operationId: getOAuthProtectedResourceMetadata
      tags:
      - Authentication
      summary: Get OAuth protected resource metadata
      description: The canonical /mcp resource advertises the complete scope catalog, matching the general protected-resource and authorization-server metadata.
      parameters:
      - name: resource
        in: query
        required: false
        schema:
          type: string
          format: uri
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  resource:
                    type: string
                    format: uri
                  authorization_servers:
                    type: array
                    items:
                      type: string
                      format: uri
                  resource_documentation:
                    type: string
                    format: uri
                  scopes_supported:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalScope'
                  commentary_resources:
                    type: array
                    items:
                      type: string
                      format: uri
                  commentary_openapi:
                    type: string
                    format: uri
                additionalProperties: true
    servers:
    - url: https://commentary.dev
      description: Configured Commentary origin.
    - url: http://localhost:3000
      description: Local development.
  /oauth/register:
    post:
      operationId: registerOAuthClient
      tags:
      - Authentication
      summary: Register a public OAuth client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_name:
                  type: string
                redirect_uris:
                  type: array
                  items:
                    type: string
                    format: uri
                grant_types:
                  type: array
                  items:
                    type: string
                response_types:
                  type: array
                  items:
                    type: string
                scope:
                  type: string
                token_endpoint_auth_method:
                  type: string
                  enum:
                  - none
              additionalProperties: true
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id:
                    type: string
                  client_name:
                    type:
                    - string
                    - 'null'
                  redirect_uris:
                    type: array
                    items:
                      type: string
                  token_endpoint_auth_method:
                    type: string
                    enum:
                    - none
                additionalProperties: true
        '400':
          description: OAuth request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '429':
          description: The request was rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
    servers:
    - url: https://commentary.dev
      description: Configured Commentary origin.
    - url: http://localhost:3000
      description: Local development.
  /oauth/authorize:
    get:
      operationId: showOAuthAuthorizePage
      tags:
      - Authentication
      summary: Show the OAuth authorization page
      description: When a client omits scope for the canonical /mcp resource, the signed-in user chooses read-only, review-and-comment, or a custom set at consent time. Omitted scope for other resources remains read-only.
      parameters:
      - name: client_id
        in: query
        required: false
        schema:
          type: string
      - name: redirect_uri
        in: query
        required: false
        schema:
          type: string
          format: uri
      - name: response_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - code
      - name: code_challenge
        in: query
        required: false
        schema:
          type: string
      - name: code_challenge_method
        in: query
        required: false
        schema:
          type: string
          enum:
          - S256
      - name: scope
        in: query
        required: false
        schema:
          type: string
      - name: resource
        in: query
        required: false
        schema:
          type: string
      - name: state
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: HTML authorization page.
        '302':
          description: Redirect to the client with an authorization error.
    post:
      operationId: approveOAuthAuthorizeRequest
      tags:
      - Authentication
      summary: Approve an OAuth authorization request
      description: Approves only the permissions displayed and selected by the user. Sensitive custom permissions require a separate confirmation.
      security:
      - commentarySession: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: true
      responses:
        '302':
          description: Redirect to the client with an authorization code or error.
    servers:
    - url: https://commentary.dev
      description: Configured Commentary origin.
    - url: http://localhost:3000
      description: Local development.
  /oauth/device/code:
    post:
      operationId: createOAuthDeviceCode
      tags:
      - Authentication
      summary: Start OAuth device authorization
      description: Scope-less requests for the canonical /mcp resource defer permission selection to the signed-in device consent page; other omitted-scope requests stay read-only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - client_id
              properties:
                client_id:
                  type: string
                scope:
                  type: string
                target:
                  $ref: '#/components/schemas/TokenTarget'
                resource:
                  type: string
                client_name:
                  type: string
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - client_id
              properties:
                client_id:
                  type: string
                scope:
                  type: string
                target:
                  $ref: '#/components/schemas/TokenTarget'
                resource:
                  type: string
                client_name:
                  type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  device_code:
                    type: string
                  user_code:
                    type: string
                  verification_uri:
                    type: string
                    format: uri
                  verification_uri_complete:
                    type: string
                    format: uri
                  expires_in:
                    type: integer
                  interval:
                    type: integer
        '400':
          description: OAuth request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '429':
          description: The request was rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
    servers:
    - url: https://commentary.dev
      description: Configured Commentary origin.
    - url: http://localhost:3000
      description: Local development.
  /oauth/token:
    post:
      operationId: exchangeOAuthToken
      tags:
      - Authentication
      summary: Exchange OAuth authorization code, device code, or refresh token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - grant_type
              properties:
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  - refresh_token
                  - urn:ietf:params:oauth:grant-type:device_code
                code:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                client_id:
                  type: string
                code_verifier:
                  type: string
                refresh_token:
                  type: string
                device_code:
                  type: string
                resource:
                  type: string
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              properties:
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  - refresh_token
                  - urn:ietf:params:oauth:grant-type:device_code
                code:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                client_id:
                  type: string
                code_verifier:
                  type: string
                refresh_token:
                  type: string
                device_code:
                  type: string
                resource:
                  type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthToken'
        '400':
          description: OAuth request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '401':
          description: OAuth token exchange was rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '429':
          description: The request was rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
    servers:
    - url: https://commentary.dev
      description: Configured Commentary origin.
    - url: http://localhost:3000
      description: Local development.
components:
  schemas:
    OAuthError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        error_description:
          type: string
      additionalProperties: true
    TokenTarget:
      type: string
      description: Target string such as account, github:owner/repo, github:owner/repo:pull:123, github:owner/repo:branch:main, or draft:sessionId.
    ExternalScope:
      type: string
      enum:
      - commentary.review.settings.write
      - commentary.agents.profile.write
      - commentary.review.read
      - commentary.comments.read
      - commentary.comments.write
      - commentary.comments.status
      - commentary.review.share
      - commentary.draft_reviews.delete
      - commentary.draft_reviews.share
      - commentary.review.submit
      - commentary.forms.read
      - commentary.forms.write
      - commentary.forms.submit
      - commentary.forms.writeback
      - commentary.research.read
      - commentary.research.write
      - commentary.brain.evals.read
      - commentary.brain.evals.write
      - commentary.interactions.create
      - commentary.interactions.read
      - commentary.interactions.update
      - commentary.interactions.cancel
      - commentary.interactions.fulfillment
      - commentary.inbox.read
      - commentary.workspaces.read
      - commentary.workspaces.resources.write
      - commentary.webhooks.read
      - commentary.webhooks.write
      - commentary.projects.read
      - commentary.projects.write
      - commentary.trackers.read
      - commentary.trackers.write
      - commentary.trackers.writeback
      - commentary.review_packages.read
      - commentary.review_packages.write
      - commentary.project_reviews.read
      - commentary.project_reviews.write
      - commentary.source_snapshots.read
      - commentary.source_snapshots.write
      - commentary.evidence.read
      - commentary.evidence.write
      - commentary.evidence.verify
    OAuthToken:
      type: object
      required:
      - access_token
      - refresh_token
      - token_type
      - expires_in
      - scope
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
          enum:
          - Bearer
        expires_in:
          type: integer
        scope:
          type: string
          description: Space-delimited scopes actually granted to this token. Registered OAuth clients may receive a subset of requested scopes.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Commentary external access token
      description: Bearer token from an API token, OAuth authorization code flow, OAuth refresh token flow, or OAuth device flow.
    commentarySession:
      type: apiKey
      in: cookie
      name: commentary_session
      description: Signed-in Commentary browser session. Used for API token management routes.
x-refined-from:
- commentary-dev-openapi.json


# --- truncated at 32 KB (490 KB total) ---
# Full source: https://artifacts.apis.io/commentary-dev/openapi/commentary-dev-authentication-api-openapi.yml