slideforge-dev OAuth API

openapi: 3.2.0
info:
  title: SlideForge OAuth API
  description: 'Agent-first PowerPoint generation. Send structured slide intents (a `form` plus typed fields) or a brief; get back a real, editable `.pptx`. The draw path is deterministic — no model renders your slide, so supplied numbers and text come out verbatim. Every response carries `status`, `fidelity` and `warnings` so an automated caller can tell whether the output is usable. $0.05 per slide; an unusable slide is not billed. Authenticate with a SlideForge API key (`Authorization: Bearer sf_live_…` or `X-API-Key`) — new accounts include 60 free slides, no credit card: https://slideforge.dev/sign-up'
  version: 5.356.0
servers:
- url: https://api.slideforge.dev
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: OAuth
paths:
  /.well-known/agent-card.json:
    get:
      tags:
      - OAuth
      summary: Agent Card
      description: A2A Protocol — Agent Card for discovery by other agents.
      operationId: agent_card__well_known_agent_card_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - OAuth
      summary: Oauth Protected Resource
      description: RFC 9728 - OAuth Protected Resource Metadata (root path).
      operationId: oauth_protected_resource__well_known_oauth_protected_resource_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /.well-known/oauth-protected-resource/{path}:
    get:
      tags:
      - OAuth
      summary: Oauth Protected Resource Subpath
      description: RFC 9728 - OAuth Protected Resource Metadata (subpath, e.g. /mcp, /mcp-connectors).
      operationId: oauth_protected_resource_subpath__well_known_oauth_protected_resource__path__get
      parameters:
      - name: path
        in: path
        required: true
        schema:
          type: string
          title: Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - OAuth
      summary: Oauth Authorization Server
      description: RFC 8414 - Authorization Server Metadata.
      operationId: oauth_authorization_server__well_known_oauth_authorization_server_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /oauth/register:
    get:
      tags:
      - OAuth
      summary: Oauth Register Info
      description: RFC 7591 - Dynamic Client Registration endpoint info (GET).
      operationId: oauth_register_info_oauth_register_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    post:
      tags:
      - OAuth
      summary: Oauth Register
      description: 'RFC 7591 - Dynamic Client Registration.


        Redirect URIs are validated to prevent open-redirect attacks:

        - HTTPS, loopback HTTP, or a private-use native-app scheme (RFC 8252 §7.1:

        cursor://, windsurf://, ...). Plain http:// to a real host stays rejected

        (cleartext), as do browser-executable schemes. PKCE — S256, enforced

        unconditionally at /oauth/authorize — is what makes custom schemes safe:

        an app that hijacks the scheme catches the code but cannot exchange it

        without the verifier. ADR-2026-08-16-dcr-custom-scheme-redirects.


        Cap of 100 registered clients enforced via LRU eviction (oldest by

        last_used_at) — friendlier than 503 for legitimate clients while

        bounding storage growth.'
      operationId: oauth_register_oauth_register_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /oauth/authorize:
    get:
      tags:
      - OAuth
      summary: Oauth Authorize
      description: OAuth 2.1 Authorization endpoint - redirects to Auth0 with PKCE.
      operationId: oauth_authorize_oauth_authorize_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /oauth/callback:
    get:
      tags:
      - OAuth
      summary: Oauth Callback
      description: OAuth callback - receives Auth0 code, redirects back to MCP client.
      operationId: oauth_callback_oauth_callback_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /oauth/revoke:
    post:
      tags:
      - OAuth
      summary: Oauth Revoke
      description: 'RFC 7009 token revocation — ADR-2026-08-01 clause 5.


        Proxies revocation to Auth0 and drops our matching grant rows. This is what lets a client''s

        "disconnect" actually kill the long-lived credential rather than merely forgetting it.


        Bounded on purpose: revoking a refresh token does NOT end the session. The outstanding access

        token stays valid until `exp` (24h in prod) plus up to 30 min of middleware token cache. That

        bound exists today for every access token; this endpoint does not widen it and does not claim

        to close it.


        Per RFC 7009 §2.2 an unknown or already-revoked token is a SUCCESS, not an error — otherwise

        the endpoint becomes a token-validity oracle.'
      operationId: oauth_revoke_oauth_revoke_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /oauth/token:
    post:
      tags:
      - OAuth
      summary: Oauth Token
      description: OAuth 2.1 Token endpoint - exchanges code for access token.
      operationId: oauth_token_oauth_token_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'SlideForge API key: `Authorization: Bearer sf_live_…`. Create one at https://slideforge.dev/console/keys'
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Same key, header form — for clients that cannot set Authorization.