surfingdog-ai Keys API

openapi: 3.2.0
info:
  title: Surfing Dog Inbox Keys API
  description: Typed inbox for people and AI agents. Public routes need no auth; /v1/owner needs an owner API key.
  version: 0.2.0
tags:
- name: Keys
paths:
  /v1/owner/api-keys:
    get:
      operationId: getV1OwnerApiKeys
      tags:
      - Keys
      summary: The owner and integration keys, with their scopes, when each was last used, and…
      responses:
        '200':
          description: Keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        kind:
                          type: string
                          enum:
                          - owner
                          - integration
                        hint:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                        active:
                          type: boolean
                        created_at:
                          type: string
                          description: ISO 8601 instant
                        created_by:
                          type:
                          - string
                          - 'null'
                        last_used_at:
                          anyOf:
                          - type: string
                            description: ISO 8601 instant
                          - type: 'null'
                        expires_at:
                          anyOf:
                          - type: string
                            description: ISO 8601 instant
                          - type: 'null'
                        revoked_at:
                          anyOf:
                          - type: string
                            description: ISO 8601 instant
                          - type: 'null'
                        refusals:
                          type: array
                          items:
                            type: object
                            properties:
                              operation:
                                type: string
                              scope:
                                type: string
                              count:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                              enforced:
                                type: boolean
                              first_at:
                                type: string
                                description: ISO 8601 instant
                              last_at:
                                type: string
                                description: ISO 8601 instant
                            required:
                            - operation
                            - scope
                            - count
                            - enforced
                            - first_at
                            - last_at
                      required:
                      - id
                      - name
                      - kind
                      - hint
                      - scopes
                      - active
                      - created_at
                      - created_by
                      - last_used_at
                      - expires_at
                      - revoked_at
                      - refusals
                  apps:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type:
                          - string
                          - 'null'
                        verified:
                          type: boolean
                          description: Its details are published at its own address; otherwise it chose its own name.
                        sends_to:
                          type: array
                          items:
                            type: string
                          description: The hosts its sign-in comes back to, which receive its access.
                        scopes:
                          type: array
                          items:
                            type: string
                        connected_at:
                          type: string
                          description: ISO 8601 instant
                        last_used_at:
                          anyOf:
                          - type: string
                            description: ISO 8601 instant
                          - type: 'null'
                      required:
                      - id
                      - name
                      - verified
                      - sends_to
                      - scopes
                      - connected_at
                      - last_used_at
                    description: AI apps connected over OAuth that can still act, newest first.
                  ai_clients:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                        id:
                          type: string
                        name:
                          type:
                          - string
                          - 'null'
                        refusals:
                          type: array
                          items:
                            type: object
                            properties:
                              operation:
                                type: string
                              scope:
                                type: string
                              count:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                              enforced:
                                type: boolean
                              first_at:
                                type: string
                                description: ISO 8601 instant
                              last_at:
                                type: string
                                description: ISO 8601 instant
                            required:
                            - operation
                            - scope
                            - count
                            - enforced
                            - first_at
                            - last_at
                      required:
                      - kind
                      - id
                      - name
                      - refusals
                  scopes:
                    type: array
                    items:
                      type: object
                      properties:
                        scope:
                          type: string
                        label:
                          type: string
                      required:
                      - scope
                      - label
                  presets:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        name:
                          type: string
                        scopes:
                          type: array
                          items:
                            type: string
                      required:
                      - key
                      - name
                      - scopes
                      additionalProperties: {}
                  security:
                    type: object
                    properties:
                      ai_may_create_keys:
                        type: boolean
                      enforce_scopes:
                        type: boolean
                    required:
                    - ai_may_create_keys
                    - enforce_scopes
                required:
                - items
                - apps
                - ai_clients
                - scopes
                - presets
                - security
        '401':
          description: 'No owner credentials: send an owner key, an integration key or an OAuth token.'
        '403':
          description: 'Not allowed: the problem document says why.'
        '422':
          description: 'Invalid input: the problem document names the fields to fix.'
      security:
      - ownerKey: []
    post:
      operationId: postV1OwnerApiKeys
      tags:
      - Keys
      summary: 'Create an integration key: named, scoped, revocable.'
      description: 'Give a preset (automation, shop_sync, calendar_sync, read_only) or scopes, or both. Only the owner in person creates keys: the owner''s AI (over OAuth or the owner MCP) and integration keys get 403 not_allowed.'
      responses:
        '201':
          description: The key, shown once
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  kind:
                    type: string
                    enum:
                    - owner
                    - integration
                  hint:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                  active:
                    type: boolean
                  created_at:
                    type: string
                    description: ISO 8601 instant
                  created_by:
                    type:
                    - string
                    - 'null'
                  last_used_at:
                    anyOf:
                    - type: string
                      description: ISO 8601 instant
                    - type: 'null'
                  expires_at:
                    anyOf:
                    - type: string
                      description: ISO 8601 instant
                    - type: 'null'
                  revoked_at:
                    anyOf:
                    - type: string
                      description: ISO 8601 instant
                    - type: 'null'
                  refusals:
                    type: array
                    items:
                      type: object
                      properties:
                        operation:
                          type: string
                        scope:
                          type: string
                        count:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        enforced:
                          type: boolean
                        first_at:
                          type: string
                          description: ISO 8601 instant
                        last_at:
                          type: string
                          description: ISO 8601 instant
                      required:
                      - operation
                      - scope
                      - count
                      - enforced
                      - first_at
                      - last_at
                  key:
                    description: The key, in this answer and in no other.
                    type:
                    - string
                    - 'null'
                  key_note:
                    type: string
                required:
                - id
                - name
                - kind
                - hint
                - scopes
                - active
                - created_at
                - created_by
                - last_used_at
                - expires_at
                - revoked_at
                - refusals
                - key
                - key_note
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                    - false
                  error:
                    type: array
                    items: {}
                  data: {}
                required:
                - success
                - error
                - data
        '401':
          description: 'No owner credentials: send an owner key, an integration key or an OAuth token.'
        '403':
          description: 'Not allowed: the problem document says why.'
        '422':
          description: 'Invalid input: the problem document names the fields to fix.'
      security:
      - ownerKey: []
      parameters:
      - in: header
        name: Idempotency-Key
        required: false
        description: 'Any string up to 200 characters, new for each new request. Sending the same key and body again returns the first answer (with Idempotent-Replayed: true) instead of doing it twice; the same key with a different body is refused. Keys are kept for 30 days.'
        schema:
          type: string
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                  description: 'What the key is for, as the owner will recognise it: the system it goes into, e.g. "Zapier".'
                preset:
                  description: 'A ready-made scope set: automation, shop_sync, calendar_sync or read_only. Give this or scopes (or both: they add up).'
                  type: string
                  enum:
                  - automation
                  - shop_sync
                  - calendar_sync
                  - read_only
                  - website_forms
                scopes:
                  description: The scopes, as narrow as the system needs. Never keys:write.
                  maxItems: 12
                  type: array
                  items:
                    type: string
                    enum:
                    - inbox:read
                    - inbox:write
                    - events:read
                    - catalogue:write
                    - availability:write
                    - settings:read
                    - settings:write
                    - setup:run
                    - integrations:write
                    - customers:erase
                    - money:write
                    - forms:submit
                expires_at:
                  description: When the key stops working. Omit for a key that works until revoked.
                  type: string
                  format: date-time
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
              required:
              - name
  /v1/owner/connected-apps/{id}:
    delete:
      operationId: deleteV1OwnerConnectedAppsById
      tags:
      - Keys
      summary: Disconnect an AI app
      description: 'Every token the app holds is revoked at once; to work the inbox again it must be connected again, through the consent page. Only the owner in person disconnects an app: the owner''s AI and integration keys get 403 not_allowed.'
      responses:
        '200':
          description: How many tokens were revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  disconnected:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                required:
                - disconnected
        '401':
          description: 'No owner credentials: send an owner key, an integration key or an OAuth token.'
        '403':
          description: 'Not allowed: the problem document says why.'
        '422':
          description: 'Invalid input: the problem document names the fields to fix.'
      security:
      - ownerKey: []
      parameters:
      - in: header
        name: Idempotency-Key
        required: false
        description: 'Any string up to 200 characters, new for each new request. Sending the same key and body again returns the first answer (with Idempotent-Replayed: true) instead of doing it twice; the same key with a different body is refused. Keys are kept for 30 days.'
        schema:
          type: string
          maxLength: 200
      - schema:
          type: string
        in: path
        name: id
        required: true
  /v1/owner/api-keys/{id}:
    delete:
      operationId: deleteV1OwnerApiKeysById
      tags:
      - Keys
      summary: Revoke a key, at once and for good
      responses:
        '200':
          description: Key
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  kind:
                    type: string
                    enum:
                    - owner
                    - integration
                  hint:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
                  active:
                    type: boolean
                  created_at:
                    type: string
                    description: ISO 8601 instant
                  created_by:
                    type:
                    - string
                    - 'null'
                  last_used_at:
                    anyOf:
                    - type: string
                      description: ISO 8601 instant
                    - type: 'null'
                  expires_at:
                    anyOf:
                    - type: string
                      description: ISO 8601 instant
                    - type: 'null'
                  revoked_at:
                    anyOf:
                    - type: string
                      description: ISO 8601 instant
                    - type: 'null'
                  refusals:
                    type: array
                    items:
                      type: object
                      properties:
                        operation:
                          type: string
                        scope:
                          type: string
                        count:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        enforced:
                          type: boolean
                        first_at:
                          type: string
                          description: ISO 8601 instant
                        last_at:
                          type: string
                          description: ISO 8601 instant
                      required:
                      - operation
                      - scope
                      - count
                      - enforced
                      - first_at
                      - last_at
                required:
                - id
                - name
                - kind
                - hint
                - scopes
                - active
                - created_at
                - created_by
                - last_used_at
                - expires_at
                - revoked_at
                - refusals
        '401':
          description: 'No owner credentials: send an owner key, an integration key or an OAuth token.'
        '403':
          description: 'Not allowed: the problem document says why.'
        '422':
          description: 'Invalid input: the problem document names the fields to fix.'
      security:
      - ownerKey: []
      parameters:
      - in: header
        name: Idempotency-Key
        required: false
        description: 'Any string up to 200 characters, new for each new request. Sending the same key and body again returns the first answer (with Idempotent-Replayed: true) instead of doing it twice; the same key with a different body is refused. Keys are kept for 30 days.'
        schema:
          type: string
          maxLength: 200
      - schema:
          type: string
        in: path
        name: id
        required: true
components:
  securitySchemes:
    ownerKey:
      type: http
      scheme: bearer
      description: An owner or integration key (sdi_own_…), an OAuth access token from /oauth, or the owner app's session.