Package com.auth0.client.auth

Class AuthAPI

java.lang.Object
com.auth0.client.auth.AuthAPI
public class AuthAPI extends Object
Class that provides an implementation of of the Authentication and Authorization API methods defined by the Auth0 Authentication API. Instances are created using the AuthAPI.Builder. If you are also using the ManagementAPI, it is recommended to configure each with the same DefaultHttpClient to enable both API clients to share the same Http client.

To use with a confidential client, instantiate an instance with a client secret: 

 
 AuthAPI auth = AuthAPI.newBuilder("{DOMAIN}", "{CLIENT-ID}", "{CLIENT-SECRET}").build();

To use with a public client, or when only using APIs that do not require a client secret: 

 
 AuthAPI auth = AuthAPI.newBuilder("{DOMAIN}", "{CLIENT-ID}").build();
Operations that always require a client secret will throw a InvalidStateException if the client is not created with a secret.

  • Constructor Details

    • AuthAPI

      @Deprecated public AuthAPI(String domain, String clientId, String clientSecret, HttpOptions options)
      Deprecated.
      Use the AuthAPI.Builder to configure and create instances.
      Create a new instance with the given tenant's domain, application's client id and client secret. These values can be obtained at https://manage.auth0.com/#/applications/{YOUR_CLIENT_ID}/settings. In addition, accepts an HttpOptions that will be used to configure the networking client.
      Parameters:
      domain - tenant's domain.
      clientId - the application's client id.
      clientSecret - the application's client secret.
      options - configuration options for this client instance.
      See Also:

    • AuthAPI

      @Deprecated public AuthAPI(String domain, String clientId, String clientSecret)
      Deprecated.
      Use the AuthAPI.Builder to configure and create instances.
      Create a new instance with the given tenant's domain, application's client id and client secret. These values can be obtained at https://manage.auth0.com/#/applications/{YOUR_CLIENT_ID}/settings.
      Parameters:
      domain - tenant's domain.
      clientId - the application's client id.
      clientSecret - the application's client secret.

  • Method Details

    • newBuilder

      public static AuthAPI.Builder newBuilder(String domain, String clientId, String clientSecret)
      Initialize a new AuthAPI.Builder to configure and create an instance. Use this to construct an instance with a client secret when using a confidential client (Regular Web Application).
      Parameters:
      domain - the tenant's domain. Must be a non-null valid HTTPS URL.
      clientId - the application's client ID.
      clientSecret - the applications client secret.
      Returns:
      a Builder for further configuration.

    • newBuilder

      public static AuthAPI.Builder newBuilder(String domain, String clientId)
      Initialize a new AuthAPI.Builder to configure and create an instance. Use this to construct an instance without a client secret (for example, when only using APIs that do not require a secret).
      Parameters:
      domain - the tenant's domain. Must be a non-null valid HTTPS URL.
      clientId - the application's client ID.
      Returns:
      a Builder for further configuration.

    • authorizeUrl

      public AuthorizeUrlBuilder authorizeUrl(String redirectUri)
      Creates an instance of the AuthorizeUrlBuilder with the given redirect url. i.e.: 
       
 String url = authAPI.authorizeUrl("https://me.auth0.com/callback")
      .withConnection("facebook")
      .withAudience("https://api.me.auth0.com/users")
      .withScope("openid contacts")
      .withState("my-custom-state")
      .build();
      Parameters:
      redirectUri - the URL to redirect to after authorization has been granted by the user. Your Auth0 application must have this URL as one of its Allowed Callback URLs. Must be a valid non-encoded URL.
      Returns:
      a new instance of the AuthorizeUrlBuilder to configure.

    • logoutUrl

      public LogoutUrlBuilder logoutUrl(String returnToUrl, boolean setClientId)
      Creates an instance of the LogoutUrlBuilder with the given return-to url. i.e.: 
       
 String url = authAPI.logoutUrl("https://me.auth0.com/home", true)
      .useFederated(true)
      .withAccessToken("A9CvPwFojaBIA9CvI");
      Parameters:
      returnToUrl - the URL the user should be navigated to upon logout. Must be a valid non-encoded URL.
      setClientId - whether the client_id value must be set or not. If true, the returnToUrl must be included in your Auth0 Application's Allowed Logout URLs list. If false, the returnToUrl must be included in your Auth0's Allowed Logout URLs at the Tenant level.
      Returns:
      a new instance of the LogoutUrlBuilder to configure.

    • userInfo

      public Request<UserInfo> userInfo(String accessToken)
      Request the user information related to the access token. i.e.: 
       
 try {
      UserInfo result = authAPI.userInfo("A9CvPwFojaBIA9CvI").execute().getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      accessToken - a valid access token belonging to an API signed with RS256 algorithm and containing the scope 'openid'.
      Returns:
      a Request to execute.
      See Also:

    • resetPassword

      public Request<Void> resetPassword(String email, String connection)
      Request a password reset for the given email and database connection. The response will always be successful even if there's no user associated to the given email for that database connection. i.e.: 
       
 try {
      authAPI.resetPassword("[email protected]", "db-connection").execute().getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      email - the email associated to the database user.
      connection - the database connection where the user was created.
      Returns:
      a Request to execute.
      See Also:

    • signUp

      @Deprecated public SignUpRequest signUp(String email, String username, String password, String connection)
      Deprecated.
      Use signUp(String, String, char[], String) instead.
      Creates a sign up request with the given credentials and database connection. "Requires Username" option must be turned on in the Connection's configuration first. i.e.: 
       
 try {
      Map<String, String> fields = new HashMap<String, String>();
      fields.put("age", "25);
      fields.put("city", "Buenos Aires");
      authAPI.signUp("[email protected]", "myself", "topsecret", "db-connection")
          .setCustomFields(fields)
          .execute();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      email - the desired user's email.
      username - the desired user's username.
      password - the desired user's password.
      connection - the database connection where the user is going to be created.
      Returns:
      a Request to configure and execute.

    • signUp

      public SignUpRequest signUp(String email, String username, char[] password, String connection)
      Creates a sign up request with the given credentials and database connection. "Requires Username" option must be turned on in the Connection's configuration first. i.e.: 
       
 try {
      Map<String, String> fields = new HashMap<String, String>();
      fields.put("age", "25);
      fields.put("city", "Buenos Aires");
      authAPI.signUp("[email protected]", "myself", new char[]{'s','e','c','r','e','t'}, "db-connection")
          .setCustomFields(fields)
          .execute();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      email - the desired user's email.
      username - the desired user's username.
      password - the desired user's password.
      connection - the database connection where the user is going to be created.
      Returns:
      a Request to configure and execute.
      See Also:

    • signUp

      @Deprecated public SignUpRequest signUp(String email, String password, String connection)
      Deprecated.
      Use signUp(String, char[], String) instead.
      Creates a sign up request with the given credentials and database connection. i.e.: 
       
 try {
      Map<String, String> fields = new HashMap<String, String>();
      fields.put("age", "25);
      fields.put("city", "Buenos Aires");
      authAPI.signUp("[email protected]", "topsecret", "db-connection")
          .setCustomFields(fields)
          .execute();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      email - the desired user's email.
      password - the desired user's password.
      connection - the database connection where the user is going to be created.
      Returns:
      a Request to configure and execute.

    • signUp

      public SignUpRequest signUp(String email, char[] password, String connection)
      Creates a sign up request with the given credentials and database connection. 
       
 try {
      Map<String, String> fields = new HashMap<String, String>();
      fields.put("age", "25);
      fields.put("city", "Buenos Aires");
      authAPI.signUp("[email protected]", new char[]{'s','e','c','r','e','t'}, "db-connection")
          .setCustomFields(fields)
          .execute();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      email - the desired user's email.
      password - the desired user's password.
      connection - the database connection where the user is going to be created.
      Returns:
      a Request to configure and execute.
      See Also:

    • login

      @Deprecated public TokenRequest login(String emailOrUsername, String password)
      Deprecated.
      Use login(String, char[]) instead.
      Creates a log in request using the 'Password' grant and the given credentials. i.e.: 
       
 try {
      TokenHolder result = authAPI.login("[email protected]", "topsecret")
          .setScope("openid email nickname")
          .execute();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      emailOrUsername - the identity of the user.
      password - the password of the user.
      Returns:
      a Request to configure and execute.

    • login

      public TokenRequest login(String emailOrUsername, char[] password)
      Creates a log in request using the 'Password' grant and the given credentials. This flow should only be used from highly-trusted applications that cannot do redirects. If you can use redirect-based flows from your app, we recommend using the Authorization Code Flow instead. i.e.: 
       
 try {
      TokenHolder result = authAPI.login("[email protected]", new char[]{'s','e','c','r','e','t})
          .setScope("openid email nickname")
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      emailOrUsername - the identity of the user.
      password - the password of the user.
      Returns:
      a Request to configure and execute.
      See Also:

    • login

      @Deprecated public TokenRequest login(String emailOrUsername, String password, String realm)
      Deprecated.
      Use login(String, char[], String) instead.
      Creates a log in request using the 'Password Realm' grant and the given credentials. Default used realm and audience are defined in the "API Authorization Settings" in the account's advanced settings in the Auth0 Dashboard. 
       
 try {
      TokenHolder result = authAPI.login("[email protected]", "topsecret", "my-realm")
          .setAudience("https://myapi.me.auth0.com/users")
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      emailOrUsername - the identity of the user.
      password - the password of the user.
      realm - the realm to use.
      Returns:
      a Request to configure and execute.

    • login

      public TokenRequest login(String emailOrUsername, char[] password, String realm)
      Creates a log in request using the 'Password Realm' grant and the given credentials. Default used realm and audience are defined in the "API Authorization Settings" in the account's advanced settings in the Auth0 Dashboard. This flow should only be used from highly-trusted applications that cannot do redirects. If you can use redirect-based flows from your app, we recommend using the Authorization Code Flow instead. 
       
 try {
      TokenHolder result = authAPI.login("[email protected]", new char[]{'s','e','c','r','e','t'}, "my-realm")
          .setAudience("https://myapi.me.auth0.com/users")
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      emailOrUsername - the identity of the user.
      password - the password of the user.
      realm - the realm to use.
      Returns:
      a Request to configure and execute.
      See Also:

    • exchangePasswordlessOtp

      public TokenRequest exchangePasswordlessOtp(String emailOrPhone, String realm, char[] otp)
      Creates a login request using the Passwordless grant type. Confidential clients (Regular Web Apps) must have a client secret configured on this AuthAPI instance. 
       
 try {
      TokenHolder result = authAPI.exchangePasswordlessOtp("[email protected]", "email", new char[]{'c','o','d','e'})
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      // Something happened
 }
      Parameters:
      emailOrPhone - The email or phone number of the user. Must not be null.
      realm - The realm to use. Typically "email" or "sms", unless using a custom Passwordless connection. Must not be null.
      otp - The one-time password used to authenticate using Passwordless connections. Must not be null.
      Returns:
      A request to configure and execute
      See Also:

    • requestToken

      public TokenRequest requestToken(String audience)
      Creates a request to get a Token for the given audience using the 'Client Credentials' grant. Default used realm is defined in the "API Authorization Settings" in the account's advanced settings in the Auth0 Dashboard. This operation requires that a client secret be configured for the AuthAPI client. 
       
 try {
      TokenHolder result = authAPI.requestToken("https://myapi.me.auth0.com/users")
          .setRealm("my-realm")
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      audience - the audience of the API to request access to.
      Returns:
      a Request to configure and execute.
      See Also:

    • revokeToken

      public Request<Void> revokeToken(String refreshToken)
      Creates a request to revoke an existing Refresh Token. Confidential clients (Regular Web Apps) must have a client secret configured on this AuthAPI instance. 
       
 try {
      authAPI.revokeToken("ej2E8zNEzjrcSD2edjaE")
          .execute();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      refreshToken - the refresh token to revoke.
      Returns:
      a Request to execute.
      See Also:

    • renewAuth

      public TokenRequest renewAuth(String refreshToken)
      Creates a request to renew the authentication and get fresh new credentials using a valid Refresh Token and the refresh_token grant. Confidential clients (Regular Web Apps) must have a client secret configured on this AuthAPI instance. 
       
 try {
      TokenHolder result = authAPI.renewAuth("ej2E8zNEzjrcSD2edjaE")
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      refreshToken - the refresh token to use to get fresh new credentials.
      Returns:
      a Request to configure and execute.
      See Also:

    • exchangeCode

      public TokenRequest exchangeCode(String code, String redirectUri)
      Creates a request to exchange the code obtained in the /authorize call using the 'Authorization Code' grant. This operation requires the AuthAPI instance to have a client secret configured. 
       
 try {
      TokenHolder result = authAPI.exchangeCode("SnWoFLMzApDskr", "https://me.auth0.com/callback")
          .setScope("openid name nickname")
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      code - the authorization code received from the /authorize call.
      redirectUri - the redirect uri sent on the /authorize call.
      Returns:
      a Request to configure and execute.
      See Also:

    • exchangeCodeWithVerifier

      public TokenRequest exchangeCodeWithVerifier(String code, String verifier, String redirectUri)
      Creates a request to exchange the code obtained from the /authorize call using the Authorization Code with PKCE grant. Confidential clients (Regular Web Apps) must have a client secret configured on this AuthAPI instance. 
       
 AuthAPI auth = AuthAPI.newBuilder("DOMAIN", "CLIENT-ID", "CLIENT-SECRET").build();

 SecureRandom sr = new SecureRandom();
 byte[] code = new byte[32];
 sr.nextBytes(code);
 String verifier = Base64.getUrlEncoder().withoutPadding().encodeToString(code);

 byte[] bytes = verifier.getBytes("US-ASCII");
 MessageDigest md = MessageDigest.getInstance("SHA-256");
 md.update(bytes, 0, bytes.length);
 byte[] digest = md.digest();
 String challenge = Base64.getUrlEncoder().withoutPadding().encodeToString(digest);

 // generate authorize URL with code challenge derived from verifier
 String url = auth.authorizeUrl("https://me.auth0.com/callback")
      .withCodeChallenge(challenge)
      .build();

 // on redirect, exchange code and verify challenge
 try {
      TokenHolder result = auth.exchangeCodeWithVerifier("CODE", verifier, "https://me.auth0.com/callback")
          .setScope("openid name nickname")
          .execute();
 } catch (Auth0Exception e) {
      // Something happened
 }
      Parameters:
      code - the authorization code received from the /authorize call.
      verifier - the cryptographically random key that was used to generate the code_challenge passed to /authorize
      redirectUri - the redirect uri sent on the /authorize call.
      Returns:
      a Request to configure and execute.

    • startPasswordlessEmailFlow

      public BaseRequest<PasswordlessEmailResponse> startPasswordlessEmailFlow(String email, PasswordlessEmailType type)
      Create a request to send an email containing a link or a code to begin authentication with Passwordless connections. Confidential clients (Regular Web Apps) must have a client secret configured on this AuthAPI instance. 
       
 try {
      PasswordlessEmailResponse result = authAPI.startPasswordlessEmailFlow("[email protected]", PasswordlessEmailType.CODE)
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      // Something happened
 }
      Parameters:
      email - the email address to send the code or link to. Must not be null.
      type - the type of the passwordless email request. Must not be null.
      Returns:
      a Request to configure and execute.
      See Also:

    • startPasswordlessSmsFlow

      public BaseRequest<PasswordlessSmsResponse> startPasswordlessSmsFlow(String phoneNumber)
      Create a request to send a text message containing a code to begin authentication with Passwordless connections. Confidential clients (Regular Web Apps) must have a client secret configured on this AuthAPI instance. 
       
 try {
      PasswordlessSmsResponse result = authAPI.startPasswordlessSmsFlow("+16511234567")
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      // Something happened
 }
      Parameters:
      phoneNumber - The phone number to send the code to. Must not be null.
      Returns:
      a Request to configure and execute.
      See Also:

    • exchangeMfaOtp

      public TokenRequest exchangeMfaOtp(String mfaToken, char[] otp)
      Creates a request to exchange the mfa token and one-time password (OTP) to authenticate a user with an MFA OTP Authenticator. Confidential clients (Regular Web Apps) must have a client secret configured on this AuthAPI instance. 
       
 try {
      TokenHolder result = authAPI.exchangeMfaOtp("the-mfa-token", new char[]{'a','n','o','t','p'})
          .execute()
          .getBody();
 } catch (Auth0Exception e) {
      //Something happened
 }
      Parameters:
      mfaToken - the mfa_token received from the mfa_required error that occurred during login. Must not be null.
      otp - the OTP Code provided by the user. Must not be null.
      Returns:
      a Request to configure and execute.
      See Also: