Extole Security Keys API

openapi: 3.0.1
info:
  description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
  title: Integration API - Consumer to Extole Audiences Security Keys API
  version: '1.0'
servers:
- description: Production
  url: https://{brand}.extole.io
  variables:
    brand:
      default: yourcompany
      description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: Security Keys
paths:
  /v2/settings/security/keys/jwt/{key_id}/verify-jwt:
    post:
      deprecated: true
      description: Deprecated. Verifies a JWT signature using the key material stored on the client key identified by `key_id`. The JWT `kid` header must match the key `partner_key_id`.
      operationId: verifyJwtClientKey
      parameters:
      - in: path
        name: key_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              jwt: jwt
            schema:
              $ref: '#/components/schemas/JwtClientKeyVerifyJwtRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwtClientKeyVerifyJwtResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                client_key_not_found:
                  $ref: '#/components/examples/client_key_not_found'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                jwt_missing:
                  $ref: '#/components/examples/jwt_missing'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                pgp_extole_client_key_not_found:
                  $ref: '#/components/examples/pgp_extole_client_key_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Verify JWT client key
      tags:
      - Security Keys
      x-extole-bundle: management-expert
      x-extole-visibility: expert
  /v2/settings/security/keys:
    get:
      description: Returns active (non-archived) security keys for the client. Keys store credentials and cryptographic material used by integrations, campaign components, SFTP file transfer, and outbound webhooks. Pass one or more `tags` query values; a key is returned only when it includes every supplied tag. Use `GET /v2/settings/security/keys/built` for the fully evaluated runtime form.
      operationId: listClientKeys
      parameters:
      - in: query
        name: tags
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ClientKeyResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List client keys
      tags:
      - Security Keys
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Creates a client key from a JSON request body. Supported variants include OAuth integrations, inline PGP or SSH key material, JWT signing keys, webhook secrets, and generic password or HTTP basic credentials. Set `algorithm` to select the polymorphic request and response schema. Set `type` to classify what the key is used for.
      operationId: createClientKey
      requestBody:
        content:
          application/json:
            example:
              algorithm: A128KW
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              description: description
              key: key
              name: name
              partner_key_id: partner_key_id
              tags:
              - tag
              type: JWT
            schema:
              $ref: '#/components/schemas/StringBasedClientKeyCreateRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientKeyResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                authorization_url_invalid:
                  $ref: '#/components/examples/authorization_url_invalid'
                authorization_url_invalid_uri:
                  $ref: '#/components/examples/authorization_url_invalid_uri'
                authorization_url_too_long:
                  $ref: '#/components/examples/authorization_url_too_long'
                binding_error:
                  $ref: '#/components/examples/binding_error'
                campaign_component_absolute_name_missing:
                  $ref: '#/components/examples/campaign_component_absolute_name_missing'
                campaign_component_description_out_of_range:
                  $ref: '#/components/examples/campaign_component_description_out_of_range'
                campaign_component_display_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_display_name_contains_illegal_character'
                campaign_component_display_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_display_name_out_of_range'
                campaign_component_id_missing:
                  $ref: '#/components/examples/campaign_component_id_missing'
                campaign_component_name_already_in_use:
                  $ref: '#/components/examples/campaign_component_name_already_in_use'
                campaign_component_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_name_contains_illegal_character'
                campaign_component_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_name_out_of_range'
                campaign_component_type_validation_failed:
                  $ref: '#/components/examples/campaign_component_type_validation_failed'
                circular_component_reference:
                  $ref: '#/components/examples/circular_component_reference'
                client_key_build_failed:
                  $ref: '#/components/examples/client_key_build_failed'
                client_key_duplicate_partner_key_id:
                  $ref: '#/components/examples/client_key_duplicate_partner_key_id'
                client_key_invalid:
                  $ref: '#/components/examples/client_key_invalid'
                client_key_invalid_description:
                  $ref: '#/components/examples/client_key_invalid_description'
                client_key_invalid_name:
                  $ref: '#/components/examples/client_key_invalid_name'
                client_key_invalid_partner_key_id:
                  $ref: '#/components/examples/client_key_invalid_partner_key_id'
                client_key_invalid_tag:
                  $ref: '#/components/examples/client_key_invalid_tag'
                client_key_missing:
                  $ref: '#/components/examples/client_key_missing'
                client_key_missing_algorithm:
                  $ref: '#/components/examples/client_key_missing_algorithm'
                client_key_missing_name:
                  $ref: '#/components/examples/client_key_missing_name'
                client_key_missing_type:
                  $ref: '#/components/examples/client_key_missing_type'
                client_key_not_found:
                  $ref: '#/components/examples/client_key_not_found'
                client_key_too_long:
                  $ref: '#/components/examples/client_key_too_long'
                client_key_too_short:
                  $ref: '#/components/examples/client_key_too_short'
                client_key_unsupported_type:
                  $ref: '#/components/examples/client_key_unsupported_type'
                component_facets_not_found:
                  $ref: '#/components/examples/component_facets_not_found'
                excessive_component_reference:
                  $ref: '#/components/examples/excessive_component_reference'
                external_element_in_use:
                  $ref: '#/components/examples/external_element_in_use'
                external_element_is_referenced_by_active_configuration:
                  $ref: '#/components/examples/external_element_is_referenced_by_active_configuration'
                external_elements_cannot_have_multiple_references:
                  $ref: '#/components/examples/external_elements_cannot_have_multiple_references'
                invalid_account_id:
                  $ref: '#/components/examples/invalid_account_id'
                invalid_component_installed_into_socket:
                  $ref: '#/components/examples/invalid_component_installed_into_socket'
                invalid_component_reference:
                  $ref: '#/components/examples/invalid_component_reference'
                invalid_component_reference_socket_name:
                  $ref: '#/components/examples/invalid_component_reference_socket_name'
                invalid_external_component_reference:
                  $ref: '#/components/examples/invalid_external_component_reference'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_app_key:
                  $ref: '#/components/examples/missing_app_key'
                missing_authorization_url:
                  $ref: '#/components/examples/missing_authorization_url'
                missing_lead_perfection_client_id:
                  $ref: '#/components/examples/missing_lead_perfection_client_id'
                missing_oauth_client_id:
                  $ref: '#/components/examples/missing_oauth_client_id'
                missing_password:
                  $ref: '#/components/examples/missing_password'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                missing_username:
                  $ref: '#/components/examples/missing_username'
                oauth_client_id_too_long:
                  $ref: '#/components/examples/oauth_client_id_too_long'
                orphan_external_component_reference:
                  $ref: '#/components/examples/orphan_external_component_reference'
                pgp_extole_client_key_not_found:
                  $ref: '#/components/examples/pgp_extole_client_key_not_found'
                redundant_component_reference:
                  $ref: '#/components/examples/redundant_component_reference'
                scope_too_long:
                  $ref: '#/components/examples/scope_too_long'
                self_component_reference:
                  $ref: '#/components/examples/self_component_reference'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Create client key
      tags:
      - Security Keys
      x-extole-bundle: management
      x-extole-visibility: visible
  /v2/settings/security/keys/built:
    get:
      description: Returns the built form of each matching active client key with evaluatable fields resolved for the current client context. Supports the same `tags` filter as `GET /v2/settings/security/keys`.
      operationId: listBuiltClientKeys
      parameters:
      - in: query
        name: tags
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/BuiltClientKeyResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List built client keys
      tags:
      - Security Keys
      x-extole-bundle: management
      x-extole-visibility: visible
  /v2/settings/security/keys/{key_id}/delete:
    post:
      description: Permanently deletes an archived client key. The key must not be referenced by campaign components or other platform resources.
      operationId: deleteClientKey
      parameters:
      - in: path
        name: key_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientKeyResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                client_key_associated_with_entity:
                  $ref: '#/components/examples/client_key_associated_with_entity'
                client_key_not_found:
                  $ref: '#/components/examples/client_key_not_found'
                external_element_in_use:
                  $ref: '#/components/examples/external_element_in_use'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                pgp_extole_client_key_not_found:
                  $ref: '#/components/examples/pgp_extole_client_key_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Delete client key
      tags:
      - Security Keys
      x-extole-bundle: management
      x-extole-visibility: visible
  /v2/settings/security/keys/{key_id}/unarchive:
    post:
      description: Restores a previously archived client key so it can be used again.
      operationId: unarchiveClientKey
      parameters:
      - in: path
        name: key_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientKeyResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                client_key_associated_with_entity:
                  $ref: '#/components/examples/client_key_associated_with_entity'
                client_key_not_found:
                  $ref: '#/components/examples/client_key_not_found'
                external_element_in_use:
                  $ref: '#/components/examples/external_element_in_use'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                pgp_extole_client_key_not_found:
                  $ref: '#/components/examples/pgp_extole_client_key_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Unarchive client key
      tags:
      - Security Keys
      x-extole-bundle: management
      x-extole-visibility: visible
  /v2/settings/security/keys/{key_id}:
    put:
      description: Updates an existing client key identified by `key_id`. Only fields present in the request body are changed.
      operationId: updateClientKey
      parameters:
      - in: path
        name: key_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              algorithm: A128KW
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              description: description
              key: key
              name: name
              partner_key_id: partner_key_id
            schema:
              $ref: '#/components/schemas/ClientKeyUpdateRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientKeyResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                authorization_url_invalid:
                  $ref: '#/components/examples/authorization_url_invalid'
                authorization_url_invalid_uri:
                  $ref: '#/components/examples/authorization_url_invalid_uri'
                authorization_url_too_long:
                  $ref: '#/components/examples/authorization_url_too_long'
                binding_error:
                  $ref: '#/components/examples/binding_error'
                campaign_component_absolute_name_missing:
                  $ref: '#/components/examples/campaign_component_absolute_name_missing'
                campaign_component_description_out_of_range:
                  $ref: '#/components/examples/campaign_component_description_out_of_range'
                campaign_component_display_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_display_name_contains_illegal_character'
                campaign_component_display_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_display_name_out_of_range'
                campaign_component_id_missing:
                  $ref: '#/components/examples/campaign_component_id_missing'
                campaign_component_name_already_in_use:
                  $ref: '#/components/examples/campaign_component_name_already_in_use'
                campaign_component_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_name_contains_illegal_character'
                campaign_component_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_name_out_of_range'
                campaign_component_type_validation_failed:
                  $ref: '#/components/examples/campaign_component_type_validation_failed'
                circular_component_reference:
                  $ref: '#/components/examples/circular_component_reference'
                client_key_build_failed:
                  $ref: '#/components/examples/client_key_build_failed'
                client_key_duplicate_partner_key_id:
                  $ref: '#/components/examples/client_key_duplicate_partner_key_id'
                client_key_invalid:
                  $ref: '#/components/examples/client_key_invalid'
                client_key_invalid_description:
                  $ref: '#/components/examples/client_key_invalid_description'
                client_key_invalid_name:
                  $ref: '#/components/examples/client_key_invalid_name'
                client_key_invalid_partner_key_id:
                  $ref: '#/components/examples/client_key_invalid_partner_key_id'
                client_key_invalid_tag:
                  $ref: '#/components/examples/client_key_invalid_tag'
                client_key_missing:
                  $ref: '#/components/examples/client_key_missing'
                client_key_missing_algorithm:
                  $ref: '#/components/examples/client_key_missing_algorithm'
                client_key_missing_name:
                  $ref: '#/components/examples/client_key_missing_name'
                client_key_missing_type:
                  $ref: '#/components/examples/client_key_missing_type'
                client_key_not_found:
                  $ref: '#/components/examples/client_key_not_found'
                client_key_too_long:
                  $ref: '#/components/e

# --- truncated at 32 KB (342 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-security-keys-api-openapi.yml