> ## Documentation Index
> Fetch the complete documentation index at: https://www.vitalog.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth exchange code

> Authorization-code exchange with S256 PKCE and exact client, consented callback and canonical MCP resource binding. Public clients use client_id without a secret; confidential clients use their declared client_secret_basic, client_secret_post or private_key_jwt method. JWT clients send a signed assertion with registered public keys and a unique jti; replay is blocked across restarts. Basic credentials or a verified assertion identify the client when client_id is omitted from the body. Unknown OAuth parameters are ignored. No refresh or client-credentials grants. Atomically consumes the code and creates a scoped 30-day MCP token and its API-key management record. The primary AUTH_KEY can list or revoke this record. Revocation is checked on every MCP request.



## OpenAPI

````yaml /openapi.json post /oauth/token
openapi: 3.1.1
info:
  title: Vitalog
  version: 1.0.1
  description: >-
    Single-user structured observations with equivalent REST and MCP domain
    services. Environment AUTH_KEY or revocable personal Bearer keys with
    required name, permissions and explicit expiry (including Never); Primary
    key management requires AUTH_KEY; the UI uses separate, root-verified
    30-minute management sessions. MCP clients use OAuth authorization code with
    S256 PKCE, issued after root sign-in. Clients are resolved through HTTPS
    metadata, pre-registration or dynamic registration. OAuth tokens grant MCP
    access only.
servers:
  - url: https://vitalog-api.example.com
    description: Production REST and MCP API
  - url: http://localhost:3000
    description: Loopback development; production requires TLS ingress
security: []
paths:
  /oauth/token:
    post:
      tags:
        - OAuth
      summary: OAuth exchange code
      description: >-
        Authorization-code exchange with S256 PKCE and exact client, consented
        callback and canonical MCP resource binding. Public clients use
        client_id without a secret; confidential clients use their declared
        client_secret_basic, client_secret_post or private_key_jwt method. JWT
        clients send a signed assertion with registered public keys and a unique
        jti; replay is blocked across restarts. Basic credentials or a verified
        assertion identify the client when client_id is omitted from the body.
        Unknown OAuth parameters are ignored. No refresh or client-credentials
        grants. Atomically consumes the code and creates a scoped 30-day MCP
        token and its API-key management record. The primary AUTH_KEY can list
        or revoke this record. Revocation is checked on every MCP request.
      operationId: oauth_exchange_code
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                grant_type:
                  type: string
                  const: authorization_code
                code:
                  type: string
                  pattern: ^voc_[A-Za-z0-9_-]{43}$
                client_id:
                  $ref: '#/components/schemas/Schema_e45751e7422e___schema0'
                client_secret:
                  type: string
                  minLength: 1
                  maxLength: 512
                client_assertion:
                  type: string
                  minLength: 1
                  maxLength: 3072
                client_assertion_type:
                  type: string
                  const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                redirect_uri:
                  $ref: '#/components/schemas/Schema_e45751e7422e___schema0'
                resource:
                  type: string
                  maxLength: 512
                code_verifier:
                  type: string
                  pattern: ^[A-Za-z0-9._~-]{43,128}$
              required:
                - grant_type
                - code
                - redirect_uri
                - resource
                - code_verifier
              additionalProperties: true
      responses:
        '200':
          description: 'Opaque access token; store privately. Cache-Control: no-store'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - access_token
                  - token_type
                  - expires_in
                  - scope
                properties:
                  access_token:
                    type: string
                    pattern: ^vlo_[A-Za-z0-9_-]{43}$
                    writeOnly: true
                  token_type:
                    const: Bearer
                  expires_in:
                    type: integer
                    minimum: 1
                    maximum: 2592000
                  scope:
                    type: string
        '400':
          description: OAuth protocol error
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - error
                  - error_description
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
        '401':
          description: OAuth protocol error
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - error
                  - error_description
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
        '413':
          description: Request exceeds 4 KiB
        '422':
          description: Credentials outside their supported header are rejected
      security: []
components:
  schemas:
    Schema_e45751e7422e___schema0:
      type: string
      minLength: 1
      maxLength: 512
      pattern: ^[^\s\u0000-\u001f\u007f]+$

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.