openapi: 3.0.0
info:
  title: Auth0 Authentication actions users-by-email 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: users-by-email
paths:
  /users-by-email:
    get:
      summary: Search Users by Email
      description: "Find users by email. If Auth0 is the identity provider (idP), the email address associated with a user is saved in lower case, regardless of how you initially provided it. \n\nFor example, if you register a user as JohnSmith@example.com, Auth0 saves the user's email as johnsmith@example.com. \n\nTherefore, when using this endpoint, make sure that you are searching for users via email addresses using the correct case.\n"
      tags:
      - users-by-email
      parameters:
      - name: fields
        in: query
        description: Comma-separated list of fields to include or exclude (based on value provided for include_fields) in the result. Leave empty to retrieve all fields.
        schema:
          type: string
          pattern: ^((phone_number)|(email)|(email_verified)|(picture)|(username)|(user_id)|(name)|(nickname)|(created_at)|(identities)|(app_metadata)|(user_metadata)|(last_ip)|(last_login)|(logins_count)|(updated_at)|(blocked)|(family_name)|(given_name))(,((phone_number)|(email)|(email_verified)|(picture)|(username)|(user_id)|(name)|(nickname)|(created_at)|(identities)|(app_metadata)|(user_metadata)|(last_ip)|(last_login)|(logins_count)|(updated_at)|(blocked)|(family_name)|(given_name)))*$
      - name: include_fields
        in: query
        description: Whether specified fields are to be included (true) or excluded (false). Defaults to true.
        schema:
          type: boolean
      - name: email
        in: query
        description: Email address to search for (case-sensitive).
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Users successfully searched.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserResponseSchema'
        '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: User to be acted on does not match subject in bearer token.
          x-description-1: '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_users-by-email
      x-release-lifecycle: GA
      x-operation-name: listUsersByEmail
      x-operation-request-parameters-name: ListUsersByEmailRequestParameters
      x-operation-group: users
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - read:users
components:
  schemas:
    UserResponseSchema:
      type: object
      additionalProperties: true
      properties:
        user_id:
          type: string
          description: ID of the user which can be used when interacting with other APIs.
          default: auth0|507f1f77bcf86cd799439020
        email:
          type: string
          description: Email address of this user.
          default: john.doe@gmail.com
          format: email
        email_verified:
          type: boolean
          description: Whether this email address is verified (true) or unverified (false).
          default: false
        username:
          type: string
          description: Username of this user.
          default: johndoe
        phone_number:
          type: string
          description: Phone number for this user. Follows the <a href="https://en.wikipedia.org/wiki/E.164">E.164 recommendation</a>.
          default: '+199999999999999'
        phone_verified:
          type: boolean
          description: Whether this phone number has been verified (true) or not (false).
          default: false
        created_at:
          $ref: '#/components/schemas/UserDateSchema'
        updated_at:
          $ref: '#/components/schemas/UserDateSchema'
        identities:
          type: array
          description: Array of user identity objects when accounts are linked.
          items:
            $ref: '#/components/schemas/UserIdentitySchema'
        app_metadata:
          $ref: '#/components/schemas/UserAppMetadataSchema'
        user_metadata:
          $ref: '#/components/schemas/UserMetadataSchema'
        picture:
          type: string
          description: URL to picture, photo, or avatar of this user.
        name:
          type: string
          description: Name of this user.
        nickname:
          type: string
          description: Preferred nickname or alias of this user.
        multifactor:
          type: array
          description: List of multi-factor authentication providers with which this user has enrolled.
          items:
            type: string
        last_ip:
          type: string
          description: Last IP address from which this user logged in.
        last_login:
          $ref: '#/components/schemas/UserDateSchema'
        logins_count:
          type: integer
          description: Total number of logins this user has performed.
        blocked:
          type: boolean
          description: Whether this user was blocked by an administrator (true) or is not (false).
        given_name:
          type: string
          description: Given name/first name/forename of this user.
        family_name:
          type: string
          description: Family name/last name/surname of this user.
    UserIdentitySchema:
      type: object
      additionalProperties: false
      properties:
        connection:
          type: string
          description: Name of the connection containing this identity.
        user_id:
          type: string
          description: Unique identifier of the user user for this identity.
        provider:
          $ref: '#/components/schemas/UserIdentityProviderEnum'
        isSocial:
          type: boolean
          description: Whether this identity is from a social provider (true) or not (false).
        access_token:
          type: string
          description: IDP access token returned only if scope read:user_idp_tokens is defined.
        access_token_secret:
          type: string
          description: IDP access token secret returned only if scope read:user_idp_tokens is defined.
        refresh_token:
          type: string
          description: IDP refresh token returned only if scope read:user_idp_tokens is defined.
        profileData:
          $ref: '#/components/schemas/UserProfileData'
    UserAppMetadataSchema:
      type: object
      description: User metadata to which this user has read-only access.
      additionalProperties: true
      properties: {}
    UserDateSchema:
      oneOf:
      - type: string
        description: Date and time when this user was created (ISO_8601 format).
      - type: object
        description: Date and time when this user was created (ISO_8601 format).
        additionalProperties: true
    UserProfileData:
      type: object
      additionalProperties: true
      properties:
        email:
          type: string
          description: Email address of this user.
        email_verified:
          type: boolean
          description: Whether this email address is verified (true) or unverified (false).
        name:
          type: string
          description: Name of this user.
        username:
          type: string
          description: Username of this user.
          default: johndoe
        given_name:
          type: string
          description: Given name/first name/forename of this user.
        phone_number:
          type: string
          description: Phone number for this user.
        phone_verified:
          type: boolean
          description: Whether this phone number is verified (true) or unverified (false).
        family_name:
          type: string
          description: Family name/last name/surname of this user.
    UserIdentityProviderEnum:
      type: string
      description: The type of identity provider
      enum:
      - ad
      - adfs
      - amazon
      - apple
      - dropbox
      - bitbucket
      - auth0-oidc
      - auth0
      - baidu
      - bitly
      - box
      - custom
      - daccount
      - dwolla
      - email
      - evernote-sandbox
      - evernote
      - exact
      - facebook
      - fitbit
      - github
      - google-apps
      - google-oauth2
      - instagram
      - ip
      - line
      - linkedin
      - oauth1
      - oauth2
      - office365
      - oidc
      - okta
      - paypal
      - paypal-sandbox
      - pingfederate
      - planningcenter
      - salesforce-community
      - salesforce-sandbox
      - salesforce
      - samlp
      - sharepoint
      - shopify
      - shop
      - sms
      - soundcloud
      - thirtysevensignals
      - twitter
      - untappd
      - vkontakte
      - waad
      - weibo
      - windowslive
      - wordpress
      - yahoo
      - yandex
    UserMetadataSchema:
      type: object
      description: User metadata to which this user has read/write access.
      additionalProperties: true