CMD+K Cmdk API

openapi: 3.2.0
info:
  title: CMD+K Cmdk API
  version: '2026-10-16'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-16: 5 operation(s) read from 3 public documentation page(s) (each operation names its page in x-source). This is not the provider''s published contract; CMD+K has published no machine-readable contract that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 5
    documentation: 0
    pages-with-code: 2
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-16'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://commandplusk.com/docs/monetize/ai-runtime
  - https://commandplusk.com/docs/build-mcp/authentication
  - https://commandplusk.com/docs/widget/partner-embed
security:
- bearer: []
tags:
- name: Cmdk
paths:
  /cmdk/verify-user:
    post:
      operationId: post_cmdk_verify_user
      tags:
      - Cmdk
      summary: 'Webhook Verify: POST request sent to your endpoint when a user attempts to…'
      description: 'The endpoint receives a POST with JSON body containing deployment_slug, subject, email, requested_scopes, client_hint, nonce, and timestamp. The request includes headers:

        - `content-type: application/json`

        - `x-cmdk-signature: t=,v1=` (HMAC‑SHA256 of `${timestamp}.${rawBody}` using the shared secret)

        - `x-cmdk-event: mcp_deployment.verify_user`

        - `user-agent: CommandK-MCP-Gateway/1.0`

        Your service must verify the signature, optionally reject stale timestamps, and respond with a 2xx JSON payload. Only the `allowed` field is required; other fields are optional.'
      x-source: https://commandplusk.com/docs/build-mcp/authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCmdkVerifyUserRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCmdkVerifyUserResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostCmdkVerifyUserRequest:
      type: object
      properties:
        deployment_slug:
          type: string
          description: Slug of the MCP deployment.
        subject:
          type: string
          description: User‑provided identifier (or email if left blank).
        email:
          type: string
          description: User’s email address.
        requested_scopes:
          type: array
          description: Array of scopes requested for the token (may be empty).
        client_hint:
          type: string
          description: Short free‑text label of the MCP client, or null.
        nonce:
          type: string
          description: Random 32‑character hex string.
        timestamp:
          type: integer
          description: Unix time in milliseconds; matches the t= value in the signature header.
      required:
      - deployment_slug
      - subject
      - email
      - requested_scopes
      - nonce
      - timestamp
    PostCmdkVerifyUserResponse:
      type: object
      properties:
        allowed:
          type: boolean
          description: Grant (true) or deny (false) the connection. Required.
        subject:
          type: string
          description: Optional replacement for the subject sent in the request.
        email:
          type: string
          description: Optional email to store on the end‑user record.
        display_name:
          type: string
          description: Optional display name for the end‑user.
        scopes:
          type: array
          description: Optional array of scopes to replace the requested_scopes.
        ttl_seconds:
          type: integer
          description: Optional token lifetime in seconds (default 24 h, clamped 60 s–30 days).
        reason:
          type: string
          description: Optional reason shown to the user when allowed is false.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer