openapi: 3.0.0
info:
  title: Auth0 Authentication actions hooks API
  description: Auth0 Authentication API. Endpoints for authentication and authorization using OpenID Connect, OAuth 2.0, SAML, WS-Federation, and Passwordless flows.
  version: 1.0.0
servers:
- url: '{auth0_domain}'
  description: The Authentication API is served over HTTPS.
  variables:
    auth0_domain:
      description: Auth0 domain
      default: https://demo.us.auth0.com
tags:
- name: hooks
paths:
  /hooks:
    get:
      summary: Get Hooks
      description: 'Retrieve all <a href="https://auth0.com/docs/hooks">hooks</a>. Accepts a list of fields to include or exclude in the result.

        '
      tags:
      - hooks
      parameters:
      - name: page
        in: query
        description: Page index of the results to return. First page is 0.
        schema:
          type: integer
          minimum: 0
      - name: per_page
        in: query
        description: Number of results per page.
        schema:
          type: integer
          minimum: 0
          maximum: 100
      - name: include_totals
        in: query
        description: Return results inside an object that contains the total result count (true) or as a direct array of results (false, default).
        schema:
          type: boolean
      - name: enabled
        in: query
        description: Optional filter on whether a hook is enabled (true) or disabled (false).
        schema:
          type: boolean
      - name: fields
        in: query
        description: Comma-separated list of fields to include in the result. Leave empty to retrieve all fields.
        schema:
          type: string
          pattern: ^((id)|(name)|(script)|(dependencies)|(enabled)|(triggerId))(,((id)|(name)|(script)|(dependencies)|(enabled)|(triggerId)))*$
      - name: triggerId
        in: query
        description: Retrieves hooks that match the trigger
        schema:
          $ref: '#/components/schemas/HookTriggerIdEnum'
      responses:
        '200':
          description: Hooks successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListHooksResponseContent'
        '400':
          description: Invalid request query string. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: read:hooks.'
        '404':
          description: Hook not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_hooks
      x-release-lifecycle: GA
      x-operation-name: list
      x-operation-request-parameters-name: ListHooksRequestParameters
      x-operation-group: hooks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:hooks
    post:
      summary: Create a Hook
      description: 'Create a new hook.

        '
      tags:
      - hooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHookRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateHookRequestContent'
      responses:
        '201':
          description: Hook successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateHookResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: create:hooks.'
          x-description-1: This endpoint is disabled for your tenant.
        '409':
          description: Hook with the same name already exists.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: post_hooks
      x-release-lifecycle: GA
      x-operation-name: create
      x-operation-group: hooks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - create:hooks
  /hooks/{id}:
    get:
      summary: Get a Hook
      description: 'Retrieve <a href="https://auth0.com/docs/hooks">a hook</a> by its ID. Accepts a list of fields to include in the result.

        '
      tags:
      - hooks
      parameters:
      - name: id
        in: path
        description: ID of the hook to retrieve.
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9-]*$
      - name: fields
        in: query
        description: Comma-separated list of fields to include in the result. Leave empty to retrieve all fields.
        schema:
          type: string
          pattern: ^((id)|(name)|(script)|(dependencies)|(enabled)|(triggerId))(,((id)|(name)|(script)|(dependencies)|(enabled)|(triggerId)))*$
      responses:
        '200':
          description: Hook successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHookResponseContent'
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
          x-description-1: Invalid request query string. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: read:hooks.'
        '404':
          description: Hook not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_hooks_by_id
      x-release-lifecycle: GA
      x-operation-name: get
      x-operation-request-parameters-name: GetHookRequestParameters
      x-operation-group: hooks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:hooks
    delete:
      summary: Delete a Hook
      description: 'Delete a hook.

        '
      tags:
      - hooks
      parameters:
      - name: id
        in: path
        description: ID of the hook to delete.
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9-]*$
      responses:
        '204':
          description: Hook successfully deleted.
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: delete:hooks.'
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: delete_hooks_by_id
      x-release-lifecycle: GA
      x-operation-name: delete
      x-operation-group: hooks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - delete:hooks
    patch:
      summary: Update a Hook
      description: 'Update an existing hook.

        '
      tags:
      - hooks
      parameters:
      - name: id
        in: path
        description: ID of the hook to update.
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9-]*$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHookRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateHookRequestContent'
      responses:
        '201':
          description: Hook successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateHookResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: create:hooks.'
          x-description-1: This endpoint is disabled for your tenant.
        '404':
          description: The hook does not exist
        '409':
          description: A hook with the same name already exists.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: patch_hooks_by_id
      x-release-lifecycle: GA
      x-operation-name: update
      x-operation-group: hooks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - update:hooks
  /hooks/{id}/secrets:
    get:
      summary: Get Hook Secrets
      description: "Retrieve a hook's secrets by the ID of the hook. \n"
      tags:
      - hooks
      parameters:
      - name: id
        in: path
        description: ID of the hook to retrieve secrets from.
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9-]*$
      responses:
        '200':
          description: Hook secrets successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHookSecretResponseContent'
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
          x-description-1: Invalid request query string. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: read:hooks.'
        '404':
          description: Hook not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_secrets
      x-release-lifecycle: GA
      x-operation-name: get
      x-operation-group:
      - hooks
      - secrets
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:hooks
    delete:
      summary: Delete Hook Secrets
      description: 'Delete one or more existing secrets for a given hook. Accepts an array of secret names to delete. '
      tags:
      - hooks
      parameters:
      - name: id
        in: path
        description: ID of the hook whose secrets to delete.
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9-]*$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteHookSecretRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DeleteHookSecretRequestContent'
      responses:
        '204':
          description: Hook secrets successfully deleted.
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: delete:hooks.'
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: delete_secrets
      x-release-lifecycle: GA
      x-operation-name: delete
      x-operation-group:
      - hooks
      - secrets
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - delete:hooks
    patch:
      summary: Update Hook Secrets
      description: "Update one or more existing secrets for an existing hook. Accepts an object of key-value pairs, where the key is the name of the existing secret. \n"
      tags:
      - hooks
      parameters:
      - name: id
        in: path
        description: ID of the hook whose secrets to update.
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9-]*$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHookSecretRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateHookSecretRequestContent'
      responses:
        '201':
          description: Hook secrets successfully updated.
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: create:hooks.'
          x-description-1: This endpoint is disabled for your tenant.
        '404':
          description: Hook or secret not found.
        '409':
          description: Secret with the same name already exists.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: patch_secrets
      x-release-lifecycle: GA
      x-operation-name: update
      x-operation-group:
      - hooks
      - secrets
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - update:hooks
    post:
      summary: Add Hook Secrets
      description: "Add one or more secrets to an existing hook. Accepts an object of key-value pairs, where the key is the name of the secret. A hook can have a maximum of 20 secrets. \n"
      tags:
      - hooks
      parameters:
      - name: id
        in: path
        description: The id of the hook to retrieve
        required: true
        schema:
          type: string
          pattern: ^[A-Za-z0-9-]*$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHookSecretRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateHookSecretRequestContent'
      responses:
        '201':
          description: Hook secrets successfully added.
        '400':
          description: Invalid request body. The message will vary depending on the cause.
        '401':
          description: Invalid token.
          x-description-1: Client is not global.
          x-description-2: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: create:hooks.'
          x-description-1: This endpoint is disabled for your tenant.
        '409':
          description: Secret with the same name already exists.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: post_secrets
      x-release-lifecycle: GA
      x-operation-name: create
      x-operation-group:
      - hooks
      - secrets
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - update:hooks
components:
  schemas:
    CreateHookSecretRequestContent:
      type: object
      description: Hashmap of key-value pairs where the value must be a string.
      additionalProperties:
        type: string
      minProperties: 1
      maxProperties: 20
    DeleteHookSecretRequestContent:
      type: array
      description: Array of secret names to delete.
      minItems: 1
      items:
        type: string
    UpdateHookSecretRequestContent:
      type: object
      description: Hashmap of key-value pairs where the value must be a string.
      additionalProperties:
        type: string
      minProperties: 1
      maxProperties: 20
    HookDependencies:
      type: object
      description: Dependencies of this hook used by webtask server.
      additionalProperties:
        type: string
    UpdateHookRequestContent:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        name:
          type: string
          description: Name of this hook.
          default: my-hook
          pattern: ^[a-zA-Z0-9]([ \-a-zA-Z0-9]*[a-zA-Z0-9])?$
        script:
          type: string
          description: Code to be executed when this hook runs.
          default: module.exports = function(client, scope, audience, context, cb) cb(null, access_token); };
          minLength: 1
        enabled:
          type: boolean
          description: Whether this hook will be executed (true) or ignored (false).
          default: false
        dependencies:
          $ref: '#/components/schemas/HookDependencies'
    Hook:
      type: object
      additionalProperties: false
      properties:
        triggerId:
          type: string
          description: Trigger ID
        id:
          type: string
          description: ID of this hook.
          default: '00001'
        name:
          type: string
          description: Name of this hook.
          default: hook
        enabled:
          type: boolean
          description: Whether this hook will be executed (true) or ignored (false).
          default: true
        script:
          type: string
          description: Code to be executed when this hook runs.
          default: module.exports = function(client, scope, audience, context, cb) cb(null, access_token); };
        dependencies:
          $ref: '#/components/schemas/HookDependencies'
    CreateHookRequestContent:
      type: object
      additionalProperties: false
      required:
      - name
      - script
      - triggerId
      properties:
        name:
          type: string
          description: Name of this hook.
          default: my-hook
          pattern: ^[a-zA-Z0-9]([ \-a-zA-Z0-9]*[a-zA-Z0-9])?$
        script:
          type: string
          description: Code to be executed when this hook runs.
          default: module.exports = function(client, scope, audience, context, cb) cb(null, access_token); };
          minLength: 1
        enabled:
          type: boolean
          description: Whether this hook will be executed (true) or ignored (false).
          default: false
        dependencies:
          $ref: '#/components/schemas/HookDependencies'
        triggerId:
          $ref: '#/components/schemas/HookTriggerIdEnum'
          description: Execution stage of this rule. Can be `credentials-exchange`, `pre-user-registration`, `post-user-registration`, `post-change-password`, or `send-phone-message`.
    HookTriggerIdEnum:
      type: string
      enum:
      - credentials-exchange
      - pre-user-registration
      - post-user-registration
      - post-change-password
      - send-phone-message
      description: Retrieves hooks that match the trigger
    GetHookResponseContent:
      type: object
      additionalProperties: false
      properties:
        triggerId:
          type: string
          description: Trigger ID
        id:
          type: string
          description: ID of this hook.
          default: '00001'
        name:
          type: string
          description: Name of this hook.
          default: hook
        enabled:
          type: boolean
          description: Whether this hook will be executed (true) or ignored (false).
          default: true
        script:
          type: string
          description: Code to be executed when this hook runs.
          default: module.exports = function(client, scope, audience, context, cb) cb(null, access_token); };
        dependencies:
          $ref: '#/components/schemas/HookDependencies'
    ListHooksResponseContent:
      oneOf:
      - type: array
        items:
          $ref: '#/components/schemas/Hook'
      - $ref: '#/components/schemas/ListHooksOffsetPaginatedResponseContent'
    ListHooksOffsetPaginatedResponseContent:
      type: object
      additionalProperties: false
      properties:
        start:
          type: number
        limit:
          type: number
        total:
          type: number
        hooks:
          type: array
          items:
            $ref: '#/components/schemas/Hook'
    UpdateHookResponseContent:
      type: object
      additionalProperties: false
      properties:
        triggerId:
          type: string
          description: Trigger ID
        id:
          type: string
          description: ID of this hook.
          default: '00001'
        name:
          type: string
          description: Name of this hook.
          default: hook
        enabled:
          type: boolean
          description: Whether this hook will be executed (true) or ignored (false).
          default: true
        script:
          type: string
          description: Code to be executed when this hook runs.
          default: module.exports = function(client, scope, audience, context, cb) cb(null, access_token); };
        dependencies:
          $ref: '#/components/schemas/HookDependencies'
    CreateHookResponseContent:
      type: object
      additionalProperties: false
      properties:
        triggerId:
          type: string
          description: Trigger ID
        id:
          type: string
          description: ID of this hook.
          default: '00001'
        name:
          type: string
          description: Name of this hook.
          default: hook
        enabled:
          type: boolean
          description: Whether this hook will be executed (true) or ignored (false).
          default: true
        script:
          type: string
          description: Code to be executed when this hook runs.
          default: module.exports = function(client, scope, audience, context, cb) cb(null, access_token); };
        dependencies:
          $ref: '#/components/schemas/HookDependencies'
    GetHookSecretResponseContent:
      type: object
      description: Hashmap of key-value pairs where the value must be a string.
      additionalProperties:
        type: string
      minProperties: 1
      maxProperties: 20