pricklymails-com OAuth API

openapi: 3.2.0
info:
  title: Pricklymails Com OAuth API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged oauth across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: OAuth
  description: 'OAuth 2.1 authorization server: dynamic client registration (RFC 7591), discovery metadata (RFC 8414), and the authorization-code-with-PKCE flow (authorize, consent, token).'
paths:
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - OAuth
      summary: Returns the OAuth 2.1 authorization server metadata (RFC 8414)
      description: Public and unauthenticated.
      operationId: authorization_server_metadata
      responses:
        '200':
          description: Authorization server metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationServerMetadataResponse'
  /oauth/authorize:
    get:
      tags:
      - OAuth
      summary: Starts the authorization code flow with PKCE (RFC 6749 section 4.1.1, RFC 7636…
      description: Every validation failure, from an unknown `client_id` to a malformed PKCE parameter, returns a direct `400`; the server never redirects to the client's `redirect_uri` with an error. On success it redirects the browser (`302`) to the consent page, which carries the validated parameters.
      operationId: authorize
      parameters:
      - name: response_type
        in: query
        description: Must be `code`.
        required: true
        schema:
          type: string
      - name: client_id
        in: query
        description: The requesting client's public client_id.
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        description: Must exactly match one of the client's registered URIs.
        required: true
        schema:
          type: string
      - name: scope
        in: query
        description: Requested scopes, space-delimited. Informational only.
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: Opaque anti-CSRF value, echoed back unchanged.
        required: false
        schema:
          type: string
      - name: code_challenge
        in: query
        description: PKCE code_challenge (RFC 7636).
        required: true
        schema:
          type: string
      - name: code_challenge_method
        in: query
        description: Must be `S256`.
        required: true
        schema:
          type: string
      responses:
        '302':
          description: Redirects to the consent page.
        '400':
          description: 'Any validation failure: an unknown client_id, an unregistered redirect_uri, or a malformed response_type or PKCE parameter.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
  /oauth/authorize/consent:
    post:
      tags:
      - OAuth
      summary: Records the signed-in user's decision on an authorization request
      description: 'Requires a user access token (JWT). The user may only authorize an agent they own, and an admin impersonation session is rejected with `403`. Returns the `redirect_url` the client application should navigate the browser to: the client''s `redirect_uri` carrying `iss` (RFC 9207), `state`, and either `code` (approved) or `error=access_denied` (denied). The endpoint does not issue an HTTP redirect itself, so a single-page app can call it with `fetch`. The response carries `Cache-Control: no-store` (RFC 6749 section 5.1) because the URL embeds a single-use code.'
      operationId: authorize_consent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentRequest'
        required: true
      responses:
        '200':
          description: Redirect URL for the frontend to navigate the browser to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentResponse'
        '400':
          description: Unknown client, redirect_uri mismatch, or invalid PKCE parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The caller is an admin impersonation session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: No agent with that UUID owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
  /oauth/register:
    post:
      tags:
      - OAuth
      summary: Registers an OAuth client (RFC 7591 dynamic client registration)
      description: 'No authentication is required. Every registered client is public: the response carries no `client_secret`, and the client authenticates token requests with PKCE.'
      operationId: register_client
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterClientRequest'
        required: true
      responses:
        '201':
          description: Client registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterClientResponse'
        '400':
          description: Invalid client_name or redirect_uris.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
  /oauth/token:
    post:
      tags:
      - OAuth
      summary: Issues agent access tokens (RFC 6749 sections 4.1.3 and 6)
      description: 'The body is `application/x-www-form-urlencoded`, and the `grant_type` field selects the grant:


        - `authorization_code`: redeems a single-use authorization code for a short-lived access token and a refresh token. This is a public client exchange: no client secret is checked, only the PKCE `code_verifier`.

        - `refresh_token`: exchanges a refresh token for a new access token and a new refresh token, so an agent session outlasts the access token lifetime without repeating browser consent. Each refresh token is single-use: presenting one that was already exchanged is rejected and revokes the refresh tokens of that agent and client.


        Failures use the RFC 6749 section 5.2 error shape (`{ "error": "invalid_grant" | "invalid_request" | "unsupported_grant_type" | "server_error" }`) rather than the usual `{ error: { code, message } }` envelope, without detailing which check failed. Every response, success or error, carries `Cache-Control: no-store` (RFC 6749 sections 5.1 and 5.2).'
      operationId: token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
        required: true
      responses:
        '200':
          description: Agent session token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: RFC 6749 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenErrorResponse'
components:
  schemas:
    AuthorizationServerMetadataResponse:
      type: object
      description: '`GET /.well-known/oauth-authorization-server` response body (RFC 8414 subset).'
      required:
      - issuer
      - authorization_endpoint
      - token_endpoint
      - registration_endpoint
      - scopes_supported
      - response_types_supported
      - grant_types_supported
      - code_challenge_methods_supported
      - token_endpoint_auth_methods_supported
      - authorization_response_iss_parameter_supported
      properties:
        authorization_endpoint:
          type: string
          description: The authorization endpoint URL.
        authorization_response_iss_parameter_supported:
          type: boolean
          description: '`true`: every authorization response (success and `access_denied`) carries `iss` (RFC 9207), letting a client

            that talks to more than one authorization server verify which one a given callback actually came from.'
        code_challenge_methods_supported:
          type: array
          items:
            type: string
          description: Supported PKCE code challenge methods (RFC 7636).
        grant_types_supported:
          type: array
          items:
            type: string
          description: Supported OAuth `grant_type` values.
        issuer:
          type: string
          description: 'The authorization server''s issuer identifier: its own public base URL.'
        registration_endpoint:
          type: string
          description: The dynamic client registration endpoint URL (RFC 7591).
        response_types_supported:
          type: array
          items:
            type: string
          description: Supported OAuth `response_type` values.
        scopes_supported:
          type: array
          items:
            type: string
          description: Scopes this server may grant to a client.
        token_endpoint:
          type: string
          description: The token endpoint URL.
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
          description: 'Supported token endpoint authentication methods.

            `"none"`: every registered client is public and authenticates via PKCE, not a client secret.'
    RegisterClientRequest:
      type: object
      description: '`POST /oauth/register` request body (RFC 7591 subset).'
      required:
      - client_name
      - redirect_uris
      properties:
        client_name:
          type: string
          description: Human-readable client name (RFC 7591 `client_name`).
        redirect_uris:
          type: array
          items:
            type: string
          description: Redirect URIs the client may be sent back to after authorization; at least one is required.
    ApiErrorBody:
      type: object
      description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
          description: Error detail.
    ConsentResponse:
      type: object
      description: '`POST /oauth/authorize/consent` response body.

        The caller performs the redirect itself; this endpoint never issues an HTTP 3xx, so a single-page app can call it

        with `fetch`.'
      required:
      - redirect_url
      properties:
        redirect_url:
          type: string
          description: 'Where to navigate the browser next: the client''s own `redirect_uri` carrying either `code` and

            `state` (approved) or `error=access_denied` and `state` (denied).'
    TokenRequest:
      type: object
      description: '`POST /oauth/token` request body (RFC 6749 sections 4.1.3 and 6), submitted as `application/x-www-form-urlencoded`,

        the content type every RFC-conformant OAuth client uses for the token endpoint.

        Fields are grouped by grant type: `code`, `redirect_uri`, and `code_verifier` apply only to

        `grant_type=authorization_code`; `refresh_token` applies only to `grant_type=refresh_token`.

        A field that does not apply to the presented grant type is ignored.'
      required:
      - grant_type
      - client_id
      properties:
        client_id:
          type: string
          description: The client's public `client_id`.
        code:
          type:
          - string
          - 'null'
          description: The single-use authorization code to redeem (`authorization_code` grant only).
        code_verifier:
          type:
          - string
          - 'null'
          description: 'The PKCE `code_verifier` (RFC 7636) proving possession of the `code_challenge` presented at `/oauth/authorize`

            (`authorization_code` grant only).'
        grant_type:
          type: string
          description: Either `"authorization_code"` or `"refresh_token"`.
        redirect_uri:
          type:
          - string
          - 'null'
          description: 'The redirect URI presented at `/oauth/authorize`, re-checked here per RFC 6749 section 4.1.3

            (`authorization_code` grant only).'
        refresh_token:
          type:
          - string
          - 'null'
          description: The refresh token to redeem (`refresh_token` grant only, RFC 6749 section 6).
    TokenErrorResponse:
      type: object
      description: '`POST /oauth/token` error response body (RFC 6749 section 5.2).

        Unlike the other endpoints, it is not the `{ error: { code, message } }` envelope: the shape is dictated by the

        OAuth specification that client libraries already parse.'
      required:
      - error
      properties:
        error:
          type: string
          description: 'One of RFC 6749''s defined error codes, such as `"invalid_grant"`, `"invalid_request"`, or

            `"unsupported_grant_type"`.'
    ApiErrorDetail:
      type: object
      description: Detail of an error response.
      required:
      - code
      properties:
        code:
          type: string
          description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
        message:
          type:
          - string
          - 'null'
          description: 'Present on most error kinds and equal to `code`; the API returns no localized text.

            Absent for error kinds that carry no extra detail.'
    ConsentRequest:
      type: object
      description: '`POST /oauth/authorize/consent` request body.


        Carries the authorize parameters the browser received on the consent page, plus the user''s decision.

        Every field is validated again, so a value that was valid at `GET /oauth/authorize` is still rejected if it no

        longer is.'
      required:
      - client_id
      - redirect_uri
      - code_challenge
      - code_challenge_method
      - agent_uuid
      - approve
      properties:
        agent_uuid:
          type: string
          description: Public UUID of the caller's own agent to authorize.
        approve:
          type: boolean
          description: Whether the user approved the request.
        client_id:
          type: string
          description: The client's public `client_id`.
        code_challenge:
          type: string
          description: PKCE `code_challenge` (RFC 7636).
        code_challenge_method:
          type: string
          description: PKCE `code_challenge_method`; only `"S256"` is supported.
        redirect_uri:
          type: string
          description: The redirect target, which must exactly match one of the client's registered URIs.
        state:
          type:
          - string
          - 'null'
          description: Opaque anti-CSRF value, echoed back unchanged.
    TokenResponse:
      type: object
      description: '`POST /oauth/token` success response body (RFC 6749 section 5.1).'
      required:
      - access_token
      - token_type
      - expires_in
      - scope
      - refresh_token
      properties:
        access_token:
          type: string
          description: The agent's short-lived access token (a JWT), sent as a Bearer credential.
        expires_in:
          type: integer
          format: int64
          description: Seconds until `access_token` expires.
          minimum: 0
        refresh_token:
          type: string
          description: 'A freshly minted refresh token (RFC 6749 section 5.1), issued on every successful grant (both

            `authorization_code` and `refresh_token`).

            Single-use: each exchange returns a new refresh token, and presenting one that was already exchanged is rejected

            and revokes the refresh tokens of that agent and client.'
        scope:
          type: string
          description: 'The granted scopes, space-delimited (RFC 6749 section 5.1): the agent''s own current scopes.'
        token_type:
          type: string
          description: Always `"Bearer"`.
    RegisterClientResponse:
      type: object
      description: '`POST /oauth/register` response body (RFC 7591 subset).

        There is no `client_secret`: every registered client is public and authenticates the token exchange with PKCE.'
      required:
      - client_id
      - client_name
      - redirect_uris
      properties:
        client_id:
          type: string
          description: The generated public `client_id`.
        client_name:
          type: string
          description: The registered client name, echoed back.
        redirect_uris:
          type: array
          items:
            type: string
          description: The registered redirect URIs, echoed back.
  securitySchemes:
    bearer_api_key:
      type: http
      scheme: bearer
      description: A `pm_live_*` or `pm_test_*` API key.
    jwt:
      type: http
      scheme: bearer
      description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml