openapi: 3.0.0
info:
  title: Auth0 Authentication actions user-blocks 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: user-blocks
paths:
  /user-blocks:
    get:
      summary: Get Blocks by Identifier
      description: Retrieve details of all <a href="https://auth0.com/docs/secure/attack-protection/brute-force-protection">Brute-force Protection</a> blocks for a user with the given identifier (username, phone number, or email).
      tags:
      - user-blocks
      parameters:
      - name: identifier
        in: query
        description: Should be any of a username, phone number, or email.
        required: true
        schema:
          type: string
      - name: consider_brute_force_enablement
        in: query
        description: "\n          If true and Brute Force Protection is enabled and configured to block logins, will return a list of blocked IP addresses.\n          If true and Brute Force Protection is disabled, will return an empty list.\n        "
        schema:
          type: boolean
      responses:
        '200':
          description: User successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUserBlocksByIdentifierResponseContent'
        '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: Invalid signature received for JSON Web Token validation.
        '403':
          description: 'Insufficient scope; expected any of: read:users.'
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_user-blocks
      x-release-lifecycle: GA
      x-operation-name: listByIdentifier
      x-operation-request-parameters-name: ListUserBlocksByIdentifierRequestParameters
      x-operation-group: userBlocks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:users
    delete:
      summary: Unblock by Identifier
      description: 'Remove all <a href="https://auth0.com/docs/secure/attack-protection/brute-force-protection">Brute-force Protection</a> blocks for the user with the given identifier (username, phone number, or email).


        Note: This endpoint does not unblock users that were <a href="https://auth0.com/docs/user-profile#block-and-unblock-a-user">blocked by a tenant administrator</a>.

        '
      tags:
      - user-blocks
      parameters:
      - name: identifier
        in: query
        description: Should be any of a username, phone number, or email.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: User successfully unblocked.
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
          x-description-1: Invalid request body. 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: Some fields cannot be read with the permissions granted by the bearer token scopes. The message will vary depending on the fields and the scopes.
          x-description-1: 'Insufficient scope; expected any of: update:users.'
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: delete_user-blocks
      x-release-lifecycle: GA
      x-operation-name: deleteByIdentifier
      x-operation-request-parameters-name: DeleteUserBlocksByIdentifierRequestParameters
      x-operation-group: userBlocks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - update:users
  /user-blocks/{id}:
    get:
      summary: Get a User's Blocks
      description: 'Retrieve details of all <a href="https://auth0.com/docs/secure/attack-protection/brute-force-protection">Brute-force Protection</a> blocks for the user with the given ID.

        '
      tags:
      - user-blocks
      parameters:
      - name: id
        in: path
        description: user_id of the user blocks to retrieve.
        required: true
        schema:
          type: string
      - name: consider_brute_force_enablement
        in: query
        description: "\n          If true and Brute Force Protection is enabled and configured to block logins, will return a list of blocked IP addresses.\n          If true and Brute Force Protection is disabled, will return an empty list.\n        "
        schema:
          type: boolean
      responses:
        '200':
          description: User block successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUserBlocksResponseContent'
        '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: Invalid signature received for JSON Web Token validation.
        '403':
          description: User to be acted on does not match subject in bearer token.
          x-description-1: 'Insufficient scope; expected any of: read:users.'
        '404':
          description: User not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: get_user-blocks_by_id
      x-release-lifecycle: GA
      x-operation-name: list
      x-operation-request-parameters-name: ListUserBlocksRequestParameters
      x-operation-group: userBlocks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:users
    delete:
      summary: Unblock a User
      description: 'Remove all <a href="https://auth0.com/docs/secure/attack-protection/brute-force-protection">Brute-force Protection</a> blocks for the user with the given ID.


        Note: This endpoint does not unblock users that were <a href="https://auth0.com/docs/user-profile#block-and-unblock-a-user">blocked by a tenant administrator</a>.

        '
      tags:
      - user-blocks
      parameters:
      - name: id
        in: path
        description: The user_id of the user to update.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: User successfully unblocked.
        '400':
          description: Invalid request URI. The message will vary depending on the cause.
          x-description-1: Invalid request body. 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: User to be acted on does not match subject in bearer token.
          x-description-1: Some fields cannot be read with the permissions granted by the bearer token scopes. The message will vary depending on the fields and the scopes.
          x-description-2: 'Insufficient scope; expected any of: update:users.'
        '404':
          description: User not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: delete_user-blocks_by_id
      x-release-lifecycle: GA
      x-operation-name: delete
      x-operation-group: userBlocks
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - update:users
components:
  schemas:
    UserBlockIdentifier:
      type: object
      additionalProperties: true
      properties:
        identifier:
          type: string
          description: Identifier (should be any of an `email`, `username`, or `phone_number`)
          default: john.doe@gmail.com
        ip:
          type: string
          description: IP Address
          default: 10.0.0.1
        connection:
          type: string
          description: Connection identifier
    ListUserBlocksResponseContent:
      type: object
      additionalProperties: false
      properties:
        blocked_for:
          type: array
          description: Array of identifier + IP address pairs.  IP address is optional, and may be omitted in certain circumstances (such as Account Lockout mode).
          items:
            $ref: '#/components/schemas/UserBlockIdentifier'
    ListUserBlocksByIdentifierResponseContent:
      type: object
      additionalProperties: false
      properties:
        blocked_for:
          type: array
          description: Array of identifier + IP address pairs.  IP address is optional, and may be omitted in certain circumstances (such as Account Lockout mode).
          items:
            $ref: '#/components/schemas/UserBlockIdentifier'