Working with the API

You are currently viewing the AWS SDK for Mobile documentation which is a collection of low-level libraries. Use the Amplify libraries for all new app development. Learn more

SignUp

Creates a new user in your User Pool:

1final String username = getInput(R.id.signUpUsername);
2final String password = getInput(R.id.signUpPassword);
3final Map<String, String> attributes = new HashMap<>();
4attributes.put("email", "name@email.com");
5AWSMobileClient.getInstance().signUp(username, password, attributes, null, new Callback<SignUpResult>() {
6 @Override
7 public void onResult(final SignUpResult signUpResult) {
8 runOnUiThread(new Runnable() {
9 @Override
10 public void run() {
11 Log.d(TAG, "Sign-up callback state: " + signUpResult.getConfirmationState());
12 if (!signUpResult.getConfirmationState()) {
13 final UserCodeDeliveryDetails details = signUpResult.getUserCodeDeliveryDetails();
14 makeToast("Confirm sign-up with: " + details.getDestination());
15 } else {
16 makeToast("Sign-up done.");
17 }
18 }
19 });
20 }
21
22 @Override
23 public void onError(Exception e) {
24 Log.e(TAG, "Sign-up error", e);
25 }
26});

Confirm SignUp

Confirms a new user after signing up in a User Pool:

1final String username = getInput(R.id.confirmSignUpUsername);
2final String code = getInput(R.id.confirmSignUpCode);
3AWSMobileClient.getInstance().confirmSignUp(username, code, new Callback<SignUpResult>() {
4 @Override
5 public void onResult(final SignUpResult signUpResult) {
6 runOnUiThread(new Runnable() {
7 @Override
8 public void run() {
9 Log.d(TAG, "Sign-up callback state: " + signUpResult.getConfirmationState());
10 if (!signUpResult.getConfirmationState()) {
11 final UserCodeDeliveryDetails details = signUpResult.getUserCodeDeliveryDetails();
12 makeToast("Confirm sign-up with: " + details.getDestination());
13 } else {
14 makeToast("Sign-up done.");
15 }
16 }
17 });
18 }
19
20 @Override
21 public void onError(Exception e) {
22 Log.e(TAG, "Confirm sign-up error", e);
23 }
24});

Re-send Confirmation Code

1AWSMobileClient.getInstance().resendSignUp("your_username", new Callback<SignUpResult>() {
2 @Override
3 public void onResult(SignUpResult signUpResult) {
4 Log.i(TAG, "A verification code has been sent via" +
5 signUpResult.getUserCodeDeliveryDetails().getDeliveryMedium()
6 + " at " +
7 signUpResult.getUserCodeDeliveryDetails().getDestination());
8 }
9
10 @Override
11 public void onError(Exception e) {
12 Log.e(TAG, e);
13 }
14});

SignIn

Sign in with user credentials:

1AWSMobileClient.getInstance().signIn(username, password, null, new Callback<SignInResult>() {
2 @Override
3 public void onResult(final SignInResult signInResult) {
4 runOnUiThread(new Runnable() {
5 @Override
6 public void run() {
7 Log.d(TAG, "Sign-in callback state: " + signInResult.getSignInState());
8 switch (signInResult.getSignInState()) {
9 case DONE:
10 makeToast("Sign-in done.");
11 break;
12 case SMS_MFA:
13 makeToast("Please confirm sign-in with SMS.");
14 break;
15 case NEW_PASSWORD_REQUIRED:
16 makeToast("Please confirm sign-in with new password.");
17 break;
18 default:
19 makeToast("Unsupported sign-in confirmation: " + signInResult.getSignInState());
20 break;
21 }
22 }
23 });
24 }
25
26 @Override
27 public void onError(Exception e) {
28 Log.e(TAG, "Sign-in error", e);
29 }
30});

Confirm SignIn (MFA)

In order to setup multifactor authentication, choose Manual configuration while setting up auth in the CLI. When you get to the Multifactor authentication step, choose these values:

1Multifactor authentication (MFA) user login options: ON (Required for all logins, can not be enabled later)
2For user login, select the MFA types: SMS Text Message
3Please specify an SMS authentication message: Your authentication code is {####}
4Email based user registration/forgot password: Enabled (Requires per-user email entry at registration)
5Please specify an email verification subject: Your verification code
6Please specify an email verification message: Your verification code is {####}
7Do you want to override the default password policy for this User Pool? No
8Warning: you will not be able to edit these selections.
9What attributes are required for signing up? Email, Phone Number (This attribute is not supported by Facebook, Login With Amazon.)

Note in the example above that for the What attributes are required for signing up? prompt, you need to use the arrow keys to scroll down in the list and select Phone Number. Otherwise you will not be able to add a phone number to the user and thus will not be able to sign in since SMS MFA is required.

When signing up a user, be sure to pass an attributes map including both email (in the case above where email is used for password recovery) and phone_number.

After you call sign in and get the SMS_MFA response back, you can send your user's input of the SMS code they received with the following command:

1AWSMobileClient.getInstance().confirmSignIn(signInChallengeResponse, new Callback<SignInResult>() {
2 @Override
3 public void onResult(SignInResult signInResult) {
4 Log.d(TAG, "Sign-in callback state: " + signInResult.getSignInState());
5 switch (signInResult.getSignInState()) {
6 case DONE:
7 makeToast("Sign-in done.");
8 break;
9 case SMS_MFA:
10 makeToast("Please confirm sign-in with SMS.");
11 break;
12 case NEW_PASSWORD_REQUIRED:
13 makeToast("Please confirm sign-in with new password.");
14 break;
15 default:
16 makeToast("Unsupported sign-in confirmation: " + signInResult.getSignInState());
17 break;
18 }
19 }
20
21 @Override
22 public void onError(Exception e) {
23 Log.e(TAG, "Sign-in error", e);
24 }
25});

Force Change Password

If a user is required to change their password on first login, there is a NEW_PASSWORD_REQUIRED state returned when signIn is called. You need to provide a new password given by the user in that case. It can be done using confirmSignIn with the new password.

1AWSMobileClient.getInstance().signIn("username", "password", null, new Callback<SignInResult>() {
2 @Override
3 public void onResult(final SignInResult signInResult) {
4 runOnUiThread(new Runnable() {
5 @Override
6 public void run() {
7 Log.d(TAG, "Sign-in callback state: " + signInResult.getSignInState());
8 switch (signInResult.getSignInState()) {
9 case DONE:
10 makeToast("Sign-in done.");
11 break;
12 case NEW_PASSWORD_REQUIRED:
13 makeToast("Please confirm sign-in with new password.");
14 break;
15 default:
16 makeToast("Unsupported sign-in confirmation: " + signInResult.getSignInState());
17 break;
18 }
19 }
20 });
21 }
22 @Override
23 public void onError(Exception e) {
24 Log.e(TAG, "Sign-in error", e);
25 }
26});
27
28AWSMobileClient.getInstance().confirmSignIn("NEW_PASSWORD_HERE", new Callback<SignInResult>() {
29 @Override
30 public void onResult(SignInResult signInResult) {
31 Log.d(TAG, "Sign-in callback state: " + signInResult.getSignInState());
32 switch (signInResult.getSignInState()) {
33 case DONE:
34 makeToast("Sign-in done.");
35 break;
36 case SMS_MFA:
37 makeToast("Please confirm sign-in with SMS.");
38 break;
39 default:
40 makeToast("Unsupported sign-in confirmation: " + signInResult.getSignInState());
41 break;
42 }
43 }
44 @Override
45 public void onError(Exception e) {
46 Log.e(TAG, "Sign-in error", e);
47 }
48});

Forgot Password

Forgot password is a 2 step process. You need to first call forgotPassword() method which would send a confirmation code to user via email or phone number. The details of how the code was sent are included in the response of forgotPassword(). Once the code is given by the user, you need to call confirmForgotPassword() with the confirmation code to confirm the change of password.

1AWSMobileClient.getInstance().forgotPassword("username", new Callback<ForgotPasswordResult>() {
2 @Override
3 public void onResult(final ForgotPasswordResult result) {
4 runOnUiThread(new Runnable() {
5 @Override
6 public void run() {
7 Log.d(TAG, "forgot password state: " + result.getState());
8 switch (result.getState()) {
9 case CONFIRMATION_CODE:
10 makeToast("Confirmation code is sent to reset password");
11 break;
12 default:
13 Log.e(TAG, "un-supported forgot password state");
14 break;
15 }
16 }
17 });
18 }
19
20 @Override
21 public void onError(Exception e) {
22 Log.e(TAG, "forgot password error", e);
23 }
24});
25
26AWSMobileClient.getInstance().confirmForgotPassword("username", "NEW_PASSWORD_HERE", "CONFIRMATION_CODE", new Callback<ForgotPasswordResult>() {
27 @Override
28 public void onResult(final ForgotPasswordResult result) {
29 runOnUiThread(new Runnable() {
30 @Override
31 public void run() {
32 Log.d(TAG, "forgot password state: " + result.getState());
33 switch (result.getState()) {
34 case DONE:
35 makeToast("Password changed successfully");
36 break;
37 default:
38 Log.e(TAG, "un-supported forgot password state");
39 break;
40 }
41 }
42 });
43 }
44
45 @Override
46 public void onError(Exception e) {
47 Log.e(TAG, "forgot password error", e);
48 }
49});

SignOut

1AWSMobileClient.getInstance().signOut(SignOutOptions.builder().invalidateTokens(true).build(), new Callback<Void>() {
2 @Override
3 public void onResult(Void result) {
4 Log.d(TAG, "onResult: ");
5 }
6
7 @Override
8 public void onError(Exception e) {
9 Log.e(TAG, "onError: ", e);
10 }
11});

If you want to sign out locally by just deleting tokens, you can call signOut method:

1AWSMobileClient.getInstance().signOut();

Global SignOut

Using global signout, you can signout a user from all active login sessions. By doing this, you are revoking all the OIDC tokens(id token, access token and refresh token) which means the user is signed out from all the devices. However, although the tokens are revoked, the AWS credentials will remain valid until they expire (which by default is 1 hour).

1AWSMobileClient.getInstance().signOut(SignOutOptions.builder().signOutGlobally(true).build(), new Callback<Void>() {
2 @Override
3 public void onResult(final Void result) {
4 Log.d(TAG, "signed-out");
5 }
6
7 @Override
8 public void onError(Exception e) {
9 Log.e(TAG, "sign-out error", e);
10 }
11});

Utility Properties

The AWSMobileClient provides several property "helpers" that are automatically cached locally for you to use in your application.

1AWSMobileClient.getInstance().getUsername() //String
2AWSMobileClient.getInstance().isSignedIn() //Boolean
3AWSMobileClient.getInstance().getIdentityId() //String

Managing Security Tokens

When using Authentication with AWSMobileClient, you don’t need to refresh Amazon Cognito tokens manually. The tokens are automatically refreshed by the library when necessary.

OIDC Tokens

1AWSMobileClient.getInstance().getTokens();
2AWSMobileClient.getInstance().getTokens().getIdToken().getTokenString();

AWS Credentials

1AWSMobileClient.getInstance().getCredentials();