FlashData API Keys API

openapi: 3.2.0
info:
  title: FlashData Customer API Keys API
  version: 0.2.0-draft
  summary: FlashData control-plane API contract
  description: Google search, YouTube data and media downloads, with endpoints for jobs, accounts, API keys and billing. See /docs for request examples and setup guides.
  contact:
    name: FlashData Engineering
servers:
- url: https://api.flashdata.dev/v2
  description: Management API
tags:
- name: API Keys
paths:
  /api-access/identity:
    get:
      operationId: getApiKeyIdentity
      tags:
      - API Keys
      summary: Verify current API key ownership and recurring readiness
      description: Free header-only API-key read. Returns public account/key IDs and authoritative ownership. No request body. Does not alter the existing /api-access metadata response. Shares the 120/minute account-read limit. Fail closed on unavailability; do not infer ownership from key prefix, plan, or local state. No query parameters are accepted. Responses are no-store.
      security:
      - dataApiKey: []
      responses:
        '200':
          description: Verify current API key ownership and recurring readiness
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyIdentity'
        '400':
          description: Rejected request; inspect the Problem code. Never retry a mutation blindly.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Rejected request; inspect the Problem code. Never retry a mutation blindly.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Rejected request; inspect the Problem code. Never retry a mutation blindly.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Rejected request; inspect the Problem code. Never retry a mutation blindly.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '410':
          description: Rejected request; inspect the Problem code. Never retry a mutation blindly.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Rejected request; inspect the Problem code. Never retry a mutation blindly.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rejected request; inspect the Problem code. Never retry a mutation blindly.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Rejected request; inspect the Problem code. Never retry a mutation blindly.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api-keys:
    get:
      operationId: listApiKeys
      tags:
      - API Keys
      summary: List API Key metadata
      security:
      - cookieSession: []
      responses:
        '200':
          description: API Keys without secrets
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createApiKey
      tags:
      - API Keys
      summary: Create an API Key and reveal its secret once
      security:
      - cookieSession: []
        csrfToken: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '201':
          description: Created; the same idempotent replay may return the same encrypted response for five minutes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api-keys/{keyId}:
    delete:
      operationId: revokeApiKey
      tags:
      - API Keys
      summary: Revoke an API Key
      security:
      - cookieSession: []
        csrfToken: []
      parameters:
      - $ref: '#/components/parameters/KeyId'
      responses:
        '204':
          description: Revoked
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api-keys/{keyId}/rotate:
    post:
      operationId: rotateApiKey
      tags:
      - API Keys
      summary: Create a replacement key and schedule old-key revocation
      description: Creates a new key and keeps the old key active until revokeOldAt. By default, the overlap lasts 24 hours or until the old key expires, whichever is earlier. A custom revokeOldAt must be in the future, within seven days, and no later than the old key expiry.
      security:
      - cookieSession: []
        csrfToken: []
      parameters:
      - $ref: '#/components/parameters/KeyId'
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                revokeOldAt:
                  type: string
                  format: date-time
                  description: Optional old-key revocation time; defaults to 24 hours and cannot exceed seven days or the old key expiry.
      responses:
        '201':
          description: Replacement created; secret returned once
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api-access:
    get:
      operationId: getApiAccess
      tags:
      - API Keys
      summary: Read the calling API key's authorized sources and result origin
      description: 'Free, header-only X-API-Key authentication. Returns only granted public

        source names and the configured signed-result storage origin (null if

        unavailable). No account ID, key ID, secret or storage credentials are returned.

        Local MCP revalidates this endpoint before every tool discovery and call,

        including cached result reads. No query parameters or request body are accepted.

        All /api-access routes share 120 requests per minute per client IP and return

        Cache-Control private, no-store. Normal key last-used tracking still occurs.'
      security:
      - dataApiKey: []
      responses:
        '200':
          description: Authorized public sources and result origin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          description: Too many account reads; retry after the rate-limit window
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Unauthorized:
      description: Authentication required or invalid
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: Resource not found or not owned by the caller
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: Resource state or idempotency conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ValidationError:
      description: Request validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ServiceUnavailable:
      description: A required dependency or catalog is temporarily unavailable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: Authenticated but not permitted, or CSRF validation failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    ApiKeyCreated:
      type: object
      additionalProperties: false
      required:
      - apiKey
      - secret
      properties:
        apiKey:
          $ref: '#/components/schemas/ApiKey'
        secret:
          type: string
          readOnly: true
          pattern: ^fd_(?:(?:test|live)_)?[A-Za-z0-9_-]{43}$
          description: Plaintext secret returned only by this create/rotate transaction. Newly issued secrets use the `fd_` prefix. Previously issued `fd_test_` and `fd_live_` secrets still authenticate. An authenticated replay with the same Idempotency-Key and request body may receive the same KMS-encrypted response for five minutes; it is not recoverable afterward.
          x-secret-reveal: once
    FieldError:
      type: object
      additionalProperties: false
      required:
      - field
      - code
      - message
      properties:
        field:
          type: string
        code:
          type: string
        message:
          type: string
    Problem:
      type: object
      additionalProperties: false
      required:
      - type
      - title
      - status
      - code
      - requestId
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
          minimum: 400
          maximum: 599
        code:
          type: string
          pattern: ^[a-z0-9_]+$
        detail:
          type: string
        requestId:
          type: string
          pattern: ^req_
        fieldErrors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
    ApiAccess:
      type: object
      additionalProperties: false
      required:
      - sources
      - result_origin
      properties:
        sources:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ApiAccessSource'
        result_origin:
          type:
          - string
          - 'null'
          format: uri
          description: Configured signed-result storage origin, without credentials, path, query or fragment. Not an access token or a media URL.
    ApiAccessSource:
      type: string
      enum:
      - google_search
      - google_images
      - google_news
      - google_shopping
      - google_videos
      - google_places
      - youtube_search
      - youtube_search_extended
      - youtube_metadata
      - youtube_transcript
      - youtube_captions
      - youtube_trainability
      - youtube_channel
      - youtube_suggestions
      - youtube_download
    CreateApiKeyRequest:
      type: object
      additionalProperties: false
      required:
      - name
      - scopes
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
        scopes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            enum:
            - google_search
            - google_images
            - google_news
            - google_shopping
            - google_videos
            - google_places
            - youtube_search
            - youtube_search_extended
            - youtube_metadata
            - youtube_transcript
            - youtube_captions
            - youtube_trainability
            - youtube_channel
            - youtube_suggestions
            - youtube_download
        expiresAt:
          type: string
          format: date-time
    ApiKey:
      type: object
      description: API key details. A key remains active until scheduledRevocationAt when revocation is scheduled.
      additionalProperties: false
      required:
      - id
      - name
      - prefix
      - last4
      - scopes
      - status
      - createdAt
      properties:
        id:
          type: string
          pattern: ^key_
        name:
          type: string
        prefix:
          type: string
        last4:
          type: string
          minLength: 4
          maxLength: 4
        scopes:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - active
          - revoked
          - expired
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
        scheduledRevocationAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Planned revocation time for an overlapping retiring key; null for a primary or immediately revoked key.
        createdAt:
          type: string
          format: date-time
    APIKeyIdentity:
      type: object
      additionalProperties: false
      properties:
        apiKeyId:
          type: string
        accountId:
          type: string
        accountType:
          type: string
          enum:
          - owned
          - temporary
        ownership:
          type: string
          enum:
          - owned
          - unowned
        access:
          type: string
          enum:
          - ready
          - blocked
        installed:
          type: boolean
        recurringAllowed:
          type: boolean
        connectionId:
          anyOf:
          - type: string
          - type: 'null'
        scopes:
          type: array
          items:
            type: string
        expiresAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
        verifiedAt:
          type: string
          format: date-time
      required:
      - apiKeyId
      - accountId
      - accountType
      - ownership
      - access
      - installed
      - recurringAllowed
      - connectionId
      - scopes
      - expiresAt
      - verifiedAt
      description: Authoritative current-record ownership and readiness. Public IDs only. recurringAllowed requires a verified active owner and, for agent-issued keys, server-confirmed installation. It is a point-in-time check, not an authorization token or permission to reuse cached data after revocation.
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 255
    KeyId:
      name: keyId
      in: path
      required: true
      schema:
        type: string
        pattern: ^key_
  securitySchemes:
    dataApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: FlashData API key. Job access is restricted to the key's source scopes.
    agentRegistrationProof:
      type: http
      scheme: bearer
      description: Persist a cryptographically random 32-byte base64url proof and exact request BEFORE sending; recover only with the same proof and body. Not an OAuth token.
    cookieSession:
      type: apiKey
      in: cookie
      name: __Host-fd_session
      description: Opaque Web session. The browser cannot read this cookie.
    agentSetupCredential:
      type: http
      scheme: bearer
      description: Temporary setup credential for status and claim creation only. Not a data API key.
    csrfToken:
      type: apiKey
      in: header
      name: X-CSRF-Token
    agentIdentityKey:
      type: http
      scheme: bearer
      description: Ordinary FlashData API key in Authorization Bearer, only on agent identity. Data queries use X-API-Key instead.
    agentHandoffProof:
      type: http
      scheme: bearer
      description: Proof used to recover the owner key and acknowledge installation. Never sent to a data query.