openapi: 3.0.0
info:
  title: Auth0 Authentication actions tickets 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: tickets
paths:
  /tickets/email-verification:
    post:
      summary: Create an Email Verification Ticket
      description: 'Create an email verification ticket for a given user. An email verification ticket is a generated URL that the user can consume to verify their email address.

        '
      tags:
      - tickets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailTicketRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/VerifyEmailTicketRequestContent'
      responses:
        '201':
          description: Ticket successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyEmailTicketResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
          x-description-1: The user does not have an email address.
          x-description-2: The user's main connection does not support this operation.
          x-description-3: An error ocurred in Auth0's identity provider.
          x-description-4: The connection with id {connection_id} does not exist.
          x-description-5: Identity connection does not exist.
          x-description-6: The user exists, but does not contain the given identity.
          x-description-7: The client does not exist
          x-description-8: The organization does not exist
          x-description-9: The user with id {user_id} is not a member of organization with id {organization_id}.
        '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: create:user_tickets.'
        '404':
          description: User not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: post_email-verification
      x-release-lifecycle: GA
      x-operation-name: verifyEmail
      x-operation-group: tickets
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - create:user_tickets
  /tickets/password-change:
    post:
      summary: Create a Password Change Ticket
      description: 'Create a password change ticket for a given user. A password change ticket is a generated URL that the user can consume to start a reset password flow.


        Note: This endpoint does not verify the given user’s identity. If you call this endpoint within your application, you must design your application to verify the user’s identity.

        '
      tags:
      - tickets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordTicketRequestContent'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ChangePasswordTicketRequestContent'
      responses:
        '201':
          description: Ticket successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangePasswordTicketResponseContent'
        '400':
          description: Invalid request body. The message will vary depending on the cause.
          x-description-1: The user does not have an email address.
          x-description-2: The user's main connection does not support this operation.
          x-description-3: An error ocurred in Auth0's identity provider.
          x-description-4: The connection with id {connection_id} does not exist.
          x-description-5: Identity connection does not exist.
          x-description-6: The user exists, but does not contain the given identity.
          x-description-7: The client does not exist
          x-description-8: The organization does not exist
          x-description-9: The user with id {user_id} is not a member of organization with id {organization_id}.
        '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: create:user_tickets.'
        '404':
          description: User not found.
        '429':
          description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
      operationId: post_password-change
      x-release-lifecycle: GA
      x-operation-name: changePassword
      x-operation-group: tickets
      security:
      - bearerAuth: []
      - oAuth2ClientCredentials:
        - create:user_tickets
components:
  schemas:
    ChangePasswordTicketRequestContent:
      type: object
      additionalProperties: false
      properties:
        result_url:
          type: string
          description: URL the user will be redirected to in the classic Universal Login experience once the ticket is used. Cannot be specified when using client_id or organization_id.
          default: http://myapp.com/callback
          format: url
        user_id:
          type: string
          description: user_id of for whom the ticket should be created.
          format: user-id
        client_id:
          type: string
          description: ID of the client (application). If provided for tenants using the New Universal Login experience, the email template and UI displays application details, and the user is prompted to redirect to the application's <a target='' href='https://auth0.com/docs/authenticate/login/auth0-universal-login/configure-default-login-routes#completing-the-password-reset-flow'>default login route</a> after the ticket is used. client_id is required to use the <a target='' href='https://auth0.com/docs/customize/actions/flows-and-triggers/post-change-password-flow'>Password Reset Post Challenge</a> trigger.
          default: DaM8bokEXBWrTUFCiJjWn50jei6ardyX
          format: client-id
        organization_id:
          type: string
          description: (Optional) Organization ID – the ID of the Organization. If provided, organization parameters will be made available to the email template and organization branding will be applied to the prompt. In addition, the redirect link in the prompt will include organization_id and organization_name query string parameters.
          default: org_2eondWoxcMIpaLQc
          format: organization-id
        connection_id:
          type: string
          description: ID of the connection. If provided, allows the user to be specified using email instead of user_id. If you set this value, you must also send the email parameter. You cannot send user_id when specifying a connection_id.
          default: con_0000000000000001
          pattern: ^con_[A-Za-z0-9]{16}$
        email:
          type: string
          description: Email address of the user for whom the tickets should be created. Requires the connection_id parameter. Cannot be specified when using user_id.
          format: email
        ttl_sec:
          type: integer
          description: Number of seconds for which the ticket is valid before expiration. If unspecified or set to 0, this value defaults to 432000 seconds (5 days).
          minimum: 0
        mark_email_as_verified:
          type: boolean
          description: Whether to set the email_verified attribute to true (true) or whether it should not be updated (false).
          default: false
        includeEmailInRedirect:
          type: boolean
          description: Whether to include the email address as part of the returnUrl in the reset_email (true), or not (false).
        identity:
          $ref: '#/components/schemas/ChangePasswordTicketIdentity'
          x-release-lifecycle: EA
    IdentityProviderOnlyAuth0Enum:
      type: string
      description: Identity provider name of the identity. Only `auth0` is supported
      default: auth0
      enum:
      - auth0
    VerifyEmailTicketRequestContent:
      type: object
      additionalProperties: false
      required:
      - user_id
      properties:
        result_url:
          type: string
          description: URL the user will be redirected to in the classic Universal Login experience once the ticket is used. Cannot be specified when using client_id or organization_id.
          default: http://myapp.com/callback
          format: url
        user_id:
          type: string
          description: user_id of for whom the ticket should be created.
          format: user-id
        client_id:
          type: string
          description: ID of the client (application). If provided for tenants using the New Universal Login experience, the email template and UI displays application details, and the user is prompted to redirect to the application's <a target='' href='https://auth0.com/docs/authenticate/login/auth0-universal-login/configure-default-login-routes#completing-the-password-reset-flow'>default login route</a> after the ticket is used. client_id is required to use the <a target='' href='https://auth0.com/docs/customize/actions/flows-and-triggers/post-change-password-flow'>Password Reset Post Challenge</a> trigger.
          default: DaM8bokEXBWrTUFCiJjWn50jei6ardyX
          format: client-id
        organization_id:
          type: string
          description: (Optional) Organization ID – the ID of the Organization. If provided, organization parameters will be made available to the email template and organization branding will be applied to the prompt. In addition, the redirect link in the prompt will include organization_id and organization_name query string parameters.
          default: org_2eondWoxcMIpaLQc
          format: organization-id
        ttl_sec:
          type: integer
          description: Number of seconds for which the ticket is valid before expiration. If unspecified or set to 0, this value defaults to 432000 seconds (5 days).
          minimum: 0
        includeEmailInRedirect:
          type: boolean
          description: Whether to include the email address as part of the returnUrl in the reset_email (true), or not (false).
        identity:
          $ref: '#/components/schemas/Identity'
    Identity:
      type: object
      description: This must be provided to verify primary social, enterprise and passwordless email identities. Also, is needed to verify secondary identities.
      additionalProperties: false
      required:
      - user_id
      - provider
      properties:
        user_id:
          type: string
          description: user_id of the identity to be verified.
          default: 5457edea1b8f22891a000004
        provider:
          $ref: '#/components/schemas/IdentityProviderEnum'
        connection_id:
          type: string
          description: connection_id of the identity.
          pattern: ^con_[A-Za-z0-9]{16}$
    IdentityProviderEnum:
      type: string
      description: Identity provider name of the identity (e.g. `google-oauth2`).
      default: google-oauth2
      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
    VerifyEmailTicketResponseContent:
      type: object
      additionalProperties: true
      required:
      - ticket
      properties:
        ticket:
          type: string
          description: URL representing the ticket.
          default: https://login.auth0.com/lo/verify_email?client_id=nsaPS2p3cargoFy82WT7betaOPOt3qSh&tenant=mdocs&bewit=bmNlR01CcDNOUE1GeXVzODJXVDdyY1RUT1BPdDNxU2hcMTQzMDY2MjE4MVxuRTcxM0RSeUNlbEpzUUJmaFVaS3A1NEdJbWFzSUZMYzRTdEFtY2NMMXhZPVx7ImVtYWloojoiZGFtaWtww2NoQGhvdG1haWwuY29tIiwidGVuYW50IjoiZHNjaGVua2tjwWFuIiwiY2xpZW50X2lkIjoibmNlR01CcDNOUE1GeXVzODJXVDdyY1RUT1BPiiqxU2giLCJjb25uZWN0aW9uIjoiRGFtaWmsdiwicmVzdWx0VXJsIjoiIn0
          format: url
    ChangePasswordTicketResponseContent:
      type: object
      additionalProperties: true
      required:
      - ticket
      properties:
        ticket:
          type: string
          description: URL representing the ticket.
          default: https://login.auth0.com/lo/reset?client_id=nsaPS2p3cargoFy82WT7betaOPOt3qSh&tenant=mdocs&bewit=bmNlR01CcDNOUE1GeXVzODJXVDdyY1RUT1BPdDNxU2hcMTQzMDY2MjE4MVxuRTcxM0RSeUNlbEpzUUJmaFVaS3A1NEdJbWFzSUZMYzRTdEFtY2NMMXhZPVx7ImVtYWloojoiZGFtaWtww2NoQGhvdG1haWwuY29tIiwidGVuYW50IjoiZHNjaGVua2tjwWFuIiwiY2xpZW50X2lkIjoibmNlR01CcDNOUE1GeXVzODJXVDdyY1RUT1BPiiqxU2giLCJjb25uZWN0aW9uIjoiRGFtaWmsdiwicmVzdWx0VXJsIjoiIn0
          format: url
    ChangePasswordTicketIdentity:
      type: object
      description: The user's identity. If you set this value, you must also send the user_id parameter.
      additionalProperties: false
      required:
      - user_id
      - provider
      x-release-lifecycle: EA
      properties:
        user_id:
          type: string
          description: user_id of the identity.
          default: 5457edea1b8f22891a000004
        provider:
          $ref: '#/components/schemas/IdentityProviderOnlyAuth0Enum'
        connection_id:
          type: string
          description: connection_id of the identity.
          pattern: ^con_[A-Za-z0-9]{16}$