openapi: 3.0.3
info:
  title: Knock Audiences Accounts API
  version: '1.0'
  description: Manage static Audiences and their members. Audiences power lifecycle messaging — when a user joins an audience, configured workflows fire automatically.
  contact:
    name: Knock
    url: https://knock.app
  license:
    name: Proprietary
servers:
- url: https://api.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- description: Resources for managing your Knock account.
  name: Accounts
paths:
  /v1/whoami:
    get:
      callbacks: {}
      description: Return information about the current calling scope. Will either be a service token or from an OAuth context.
      operationId: getWhoami
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhoamiResponse'
          description: OK
      summary: Verify scope
      tags:
      - Accounts
components:
  schemas:
    WhoamiResponse:
      description: Information about the current calling scope.
      example:
        account_features:
          batch_items_render_limit_allowed: false
          custom_branding_allowed: false
          data_retention_days: 30
          data_warehouse_extension_allowed: false
          datadog_extension_allowed: true
          dsync_allowed: false
          guides_monthly_notified_recipients_limit: 500
          guides_per_tenant_scope_allowed: false
          heap_extension_allowed: false
          knock_branding_required: true
          litmus_email_preview_allowed: false
          message_sent_limit: 10000
          new_relic_extension_allowed: false
          segment_extension_allowed: false
          self_serve_allowed: true
          sso_allowed: false
          tenant_preferences_allowed: false
          translations_allowed: false
        account_name: Acme, Inc.
        account_slug: acme
        service_token_name: My Service Token
        type: service_token
        user_id: null
      properties:
        account_features:
          description: Account plan features and limits.
          properties:
            batch_items_render_limit_allowed:
              description: Whether batch rendering limits can be configured.
              type: boolean
              x-struct: null
              x-validate: null
            custom_branding_allowed:
              description: Whether custom branding can be applied to notifications.
              type: boolean
              x-struct: null
              x-validate: null
            data_retention_days:
              description: Number of days data is retained, null for unlimited retention.
              nullable: true
              type: integer
              x-struct: null
              x-validate: null
            data_warehouse_extension_allowed:
              description: Whether data warehouse integration extensions are available.
              type: boolean
              x-struct: null
              x-validate: null
            datadog_extension_allowed:
              description: Whether Datadog integration extension is available.
              type: boolean
              x-struct: null
              x-validate: null
            dsync_allowed:
              description: Whether directory sync functionality is available.
              type: boolean
              x-struct: null
              x-validate: null
            guides_monthly_notified_recipients_limit:
              description: Monthly limit for guide notification recipients, null for unlimited.
              nullable: true
              type: integer
              x-struct: null
              x-validate: null
            guides_per_tenant_scope_allowed:
              description: Whether per-tenant scope for guide messages is allowed.
              type: boolean
              x-struct: null
              x-validate: null
            heap_extension_allowed:
              description: Whether Heap integration extension is available.
              type: boolean
              x-struct: null
              x-validate: null
            knock_branding_required:
              description: Whether Knock branding is required to be displayed.
              type: boolean
              x-struct: null
              x-validate: null
            litmus_email_preview_allowed:
              description: Whether Litmus email preview integration is available.
              type: boolean
              x-struct: null
              x-validate: null
            message_sent_limit:
              description: Monthly limit for messages sent, null for unlimited.
              nullable: true
              type: integer
              x-struct: null
              x-validate: null
            new_relic_extension_allowed:
              description: Whether New Relic integration extension is available.
              type: boolean
              x-struct: null
              x-validate: null
            segment_extension_allowed:
              description: Whether Segment integration extension is available.
              type: boolean
              x-struct: null
              x-validate: null
            self_serve_allowed:
              description: Whether self-service account management features are available.
              type: boolean
              x-struct: null
              x-validate: null
            sso_allowed:
              description: Whether single sign-on (SSO) is enabled for the account.
              type: boolean
              x-struct: null
              x-validate: null
            tenant_preferences_allowed:
              description: Whether tenant-level preferences are supported.
              type: boolean
              x-struct: null
              x-validate: null
            translations_allowed:
              description: Whether multi-language translations are supported.
              type: boolean
              x-struct: null
              x-validate: null
          type: object
          x-struct: null
          x-validate: null
        account_name:
          description: The display name of the account.
          type: string
          x-struct: null
          x-validate: null
        account_slug:
          description: The unique slug identifier for the account.
          type: string
          x-struct: null
          x-validate: null
        service_token_name:
          description: The name of the service token if authenticated via service token, null for OAuth contexts.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
        type:
          description: The type of authentication context - either a service token or OAuth user context.
          enum:
          - service_token
          - oauth_context
          type: string
          x-struct: null
          x-validate: null
        user_id:
          description: The ID of the authenticated user if in OAuth context, null for service token contexts.
          nullable: true
          type: string
          x-struct: null
          x-validate: null
      required:
      - account_name
      - account_slug
      - type
      - account_features
      title: WhoamiResponse
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.WhoamiResponse
      x-validate: null
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Knock API key as a Bearer token. Use a public key (pk_...) for client-side requests or a secret key (sk_...) for server-side.