public class

AccountManager

extends Object
java.lang.Object
   ↳ android.accounts.AccountManager

Class Overview

This class provides access to a centralized registry of the user's online accounts. The user enters credentials (username and password) once per account, granting applications access to online resources with "one-click" approval.

Different online services have different ways of handling accounts and authentication, so the account manager uses pluggable authenticator modules for different account types. Authenticators (which may be written by third parties) handle the actual details of validating account credentials and storing account information. For example, Google, Facebook, and Microsoft Exchange each have their own authenticator.

Many servers support some notion of an authentication token, which can be used to authenticate a request to the server without sending the user's actual password. (Auth tokens are normally created with a separate request which does include the user's credentials.) AccountManager can generate auth tokens for applications, so the application doesn't need to handle passwords directly. Auth tokens are normally reusable and cached by AccountManager, but must be refreshed periodically. It's the responsibility of applications to invalidate auth tokens when they stop working so the AccountManager knows it needs to regenerate them.

Applications accessing a server normally go through these steps:

  • Get an instance of AccountManager using get(Context).
  • List the available accounts using getAccountsByType(String) or getAccountsByTypeAndFeatures(String, String[], AccountManagerCallback, Handler). Normally applications will only be interested in accounts with one particular type, which identifies the authenticator. Account features are used to identify particular account subtypes and capabilities. Both the account type and features are authenticator-specific strings, and must be known by the application in coordination with its preferred authenticators.
  • Select one or more of the available accounts, possibly by asking the user for their preference. If no suitable accounts are available, addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback, Handler) may be called to prompt the user to create an account of the appropriate type.
  • Important: If the application is using a previously remembered account selection, it must make sure the account is still in the list of accounts returned by getAccountsByType(String). Requesting an auth token for an account no longer on the device results in an undefined failure.
  • Request an auth token for the selected account(s) using one of the getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler) methods or related helpers. Refer to the description of each method for exact usage and error handling details.
  • Make the request using the auth token. The form of the auth token, the format of the request, and the protocol used are all specific to the service you are accessing. The application may use whatever network and protocol libraries are useful.
  • Important: If the request fails with an authentication error, it could be that a cached auth token is stale and no longer honored by the server. The application must call invalidateAuthToken(String, String) to remove the token from the cache, otherwise requests will continue failing! After invalidating the auth token, immediately go back to the "Request an auth token" step above. If the process fails the second time, then it can be treated as a "genuine" authentication failure and the user notified or other appropriate actions taken.

Some AccountManager methods may need to interact with the user to prompt for credentials, present options, or ask the user to add an account. The caller may choose whether to allow AccountManager to directly launch the necessary user interface and wait for the user, or to return an Intent which the caller may use to launch the interface, or (in some cases) to install a notification which the user can select at any time to launch the interface. To have AccountManager launch the interface directly, the caller must supply the current foreground Activity context.

Many AccountManager methods take AccountManagerCallback and Handler as parameters. These methods return immediately and run asynchronously. If a callback is provided then run(AccountManagerFuture) will be invoked on the Handler's thread when the request completes, successfully or not. The result is retrieved by calling getResult() on the AccountManagerFuture returned by the method (and also passed to the callback). This method waits for the operation to complete (if necessary) and either returns the result or throws an exception if an error occurred during the operation. To make the request synchronously, call getResult() immediately on receiving the future from the method; no callback need be supplied.

Requests which may block, including getResult(), must never be called on the application's main event thread. These operations throw IllegalStateException if they are used on the main thread.

Summary

Constants
String ACTION_AUTHENTICATOR_INTENT
String AUTHENTICATOR_ATTRIBUTES_NAME
String AUTHENTICATOR_META_DATA_NAME
int ERROR_CODE_BAD_ARGUMENTS
int ERROR_CODE_BAD_REQUEST
int ERROR_CODE_CANCELED
int ERROR_CODE_INVALID_RESPONSE
int ERROR_CODE_NETWORK_ERROR
int ERROR_CODE_REMOTE_EXCEPTION
int ERROR_CODE_UNSUPPORTED_OPERATION
String KEY_ACCOUNTS
String KEY_ACCOUNT_AUTHENTICATOR_RESPONSE
String KEY_ACCOUNT_MANAGER_RESPONSE
String KEY_ACCOUNT_NAME Bundle key used for the String account name in results from methods which return information about a particular account.
String KEY_ACCOUNT_TYPE Bundle key used for the String account type in results from methods which return information about a particular account.
String KEY_AUTHENTICATOR_TYPES
String KEY_AUTHTOKEN Bundle key used for the auth token value in results from getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler) and friends.
String KEY_AUTH_FAILED_MESSAGE
String KEY_AUTH_TOKEN_LABEL
String KEY_BOOLEAN_RESULT
String KEY_ERROR_CODE
String KEY_ERROR_MESSAGE
String KEY_INTENT Bundle key used for an Intent in results from methods that may require the caller to interact with the user.
String KEY_PASSWORD Bundle key used to supply the password directly in options to confirmCredentials(Account, Bundle, Activity, AccountManagerCallback, Handler), rather than prompting the user with the standard password prompt.
String KEY_USERDATA
String LOGIN_ACCOUNTS_CHANGED_ACTION Action sent as a broadcast Intent by the AccountsService when accounts are added, accounts are removed, or an account's credentials (saved password, etc) are changed.
Public Methods
AccountManagerFuture<Bundle> addAccount(String accountType, String authTokenType, String[] requiredFeatures, Bundle addAccountOptions, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
Asks the user to add an account of a specified type.
boolean addAccountExplicitly(Account account, String password, Bundle userdata)
Adds an account directly to the AccountManager.
void addOnAccountsUpdatedListener(OnAccountsUpdateListener listener, Handler handler, boolean updateImmediately)
Adds an OnAccountsUpdateListener to this instance of the AccountManager.
String blockingGetAuthToken(Account account, String authTokenType, boolean notifyAuthFailure)
This convenience helper synchronously gets an auth token with getAuthToken(Account, String, boolean, AccountManagerCallback, Handler).
void clearPassword(Account account)
Forgets a saved password.
AccountManagerFuture<Bundle> confirmCredentials(Account account, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
Confirms that the user knows the password for an account to make extra sure they are the owner of the account.
AccountManagerFuture<Bundle> editProperties(String accountType, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
Offers the user an opportunity to change an authenticator's settings.
static AccountManager get(Context context)
Gets an AccountManager instance associated with a Context.
Account[] getAccounts()
Lists all accounts of any type registered on the device.
Account[] getAccountsByType(String type)
Lists all accounts of a particular type.
AccountManagerFuture<Account[]> getAccountsByTypeAndFeatures(String type, String[] features, AccountManagerCallback<Account[]> callback, Handler handler)
Lists all accounts of a type which have certain features.
AccountManagerFuture<Bundle> getAuthToken(Account account, String authTokenType, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
Gets an auth token of the specified type for a particular account, prompting the user for credentials if necessary.
AccountManagerFuture<Bundle> getAuthToken(Account account, String authTokenType, boolean notifyAuthFailure, AccountManagerCallback<Bundle> callback, Handler handler)
Gets an auth token of the specified type for a particular account, optionally raising a notification if the user must enter credentials.
AccountManagerFuture<Bundle> getAuthTokenByFeatures(String accountType, String authTokenType, String[] features, Activity activity, Bundle addAccountOptions, Bundle getAuthTokenOptions, AccountManagerCallback<Bundle> callback, Handler handler)
This convenience helper combines the functionality of getAccountsByTypeAndFeatures(String, String[], AccountManagerCallback, Handler), getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler), and addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback, Handler).
AuthenticatorDescription[] getAuthenticatorTypes()
Lists the currently registered authenticators.
String getPassword(Account account)
Gets the saved password associated with the account.
String getUserData(Account account, String key)
Gets the user data named by "key" associated with the account.
AccountManagerFuture<Boolean> hasFeatures(Account account, String[] features, AccountManagerCallback<Boolean> callback, Handler handler)
Finds out whether a particular account has all the specified features.
void invalidateAuthToken(String accountType, String authToken)
Removes an auth token from the AccountManager's cache.
String peekAuthToken(Account account, String authTokenType)
Gets an auth token from the AccountManager's cache.
AccountManagerFuture<Boolean> removeAccount(Account account, AccountManagerCallback<Boolean> callback, Handler handler)
Removes an account from the AccountManager.
void removeOnAccountsUpdatedListener(OnAccountsUpdateListener listener)
Removes an OnAccountsUpdateListener previously registered with addOnAccountsUpdatedListener(OnAccountsUpdateListener, Handler, boolean).
void setAuthToken(Account account, String authTokenType, String authToken)
Adds an auth token to the AccountManager cache for an account.
void setPassword(Account account, String password)
Sets or forgets a saved password.
void setUserData(Account account, String key, String value)
Sets one userdata key for an account.
AccountManagerFuture<Bundle> updateCredentials(Account account, String authTokenType, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
Asks the user to enter a new password for an account, updating the saved credentials for the account.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String ACTION_AUTHENTICATOR_INTENT

Since: API Level 5

Constant Value: "android.accounts.AccountAuthenticator"

public static final String AUTHENTICATOR_ATTRIBUTES_NAME

Since: API Level 5

Constant Value: "account-authenticator"

public static final String AUTHENTICATOR_META_DATA_NAME

Since: API Level 5

Constant Value: "android.accounts.AccountAuthenticator"

public static final int ERROR_CODE_BAD_ARGUMENTS

Since: API Level 5

Constant Value: 7 (0x00000007)

public static final int ERROR_CODE_BAD_REQUEST

Since: API Level 5

Constant Value: 8 (0x00000008)

public static final int ERROR_CODE_CANCELED

Since: API Level 5

Constant Value: 4 (0x00000004)

public static final int ERROR_CODE_INVALID_RESPONSE

Since: API Level 5

Constant Value: 5 (0x00000005)

public static final int ERROR_CODE_NETWORK_ERROR

Since: API Level 5

Constant Value: 3 (0x00000003)

public static final int ERROR_CODE_REMOTE_EXCEPTION

Since: API Level 5

Constant Value: 1 (0x00000001)

public static final int ERROR_CODE_UNSUPPORTED_OPERATION

Since: API Level 5

Constant Value: 6 (0x00000006)

public static final String KEY_ACCOUNTS

Since: API Level 5

Constant Value: "accounts"

public static final String KEY_ACCOUNT_AUTHENTICATOR_RESPONSE

Since: API Level 5

Constant Value: "accountAuthenticatorResponse"

public static final String KEY_ACCOUNT_MANAGER_RESPONSE

Since: API Level 5

Constant Value: "accountManagerResponse"

public static final String KEY_ACCOUNT_NAME

Since: API Level 5

Bundle key used for the String account name in results from methods which return information about a particular account.

Constant Value: "authAccount"

public static final String KEY_ACCOUNT_TYPE

Since: API Level 5

Bundle key used for the String account type in results from methods which return information about a particular account.

Constant Value: "accountType"

public static final String KEY_AUTHENTICATOR_TYPES

Since: API Level 5

Constant Value: "authenticator_types"

public static final String KEY_AUTHTOKEN

Since: API Level 5

Bundle key used for the auth token value in results from getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler) and friends.

Constant Value: "authtoken"

public static final String KEY_AUTH_FAILED_MESSAGE

Since: API Level 5

Constant Value: "authFailedMessage"

public static final String KEY_AUTH_TOKEN_LABEL

Since: API Level 5

Constant Value: "authTokenLabelKey"

public static final String KEY_BOOLEAN_RESULT

Since: API Level 5

Constant Value: "booleanResult"

public static final String KEY_ERROR_CODE

Since: API Level 5

Constant Value: "errorCode"

public static final String KEY_ERROR_MESSAGE

Since: API Level 5

Constant Value: "errorMessage"

public static final String KEY_INTENT

Since: API Level 5

Bundle key used for an Intent in results from methods that may require the caller to interact with the user. The Intent can be used to start the corresponding user interface activity.

Constant Value: "intent"

public static final String KEY_PASSWORD

Since: API Level 5

Bundle key used to supply the password directly in options to confirmCredentials(Account, Bundle, Activity, AccountManagerCallback, Handler), rather than prompting the user with the standard password prompt.

Constant Value: "password"

public static final String KEY_USERDATA

Since: API Level 5

Constant Value: "userdata"

public static final String LOGIN_ACCOUNTS_CHANGED_ACTION

Since: API Level 5

Action sent as a broadcast Intent by the AccountsService when accounts are added, accounts are removed, or an account's credentials (saved password, etc) are changed.

See Also
Constant Value: "android.accounts.LOGIN_ACCOUNTS_CHANGED"

Public Methods

public AccountManagerFuture<Bundle> addAccount (String accountType, String authTokenType, String[] requiredFeatures, Bundle addAccountOptions, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)

Since: API Level 5

Asks the user to add an account of a specified type. The authenticator for this account type processes this request with the appropriate user interface. If the user does elect to create a new account, the account name is returned.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission MANAGE_ACCOUNTS.

Parameters
accountType The type of account to add; must not be null
authTokenType The type of auth token (see getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler)) this account will need to be able to generate, null for none
requiredFeatures The features (see hasFeatures(Account, String[], AccountManagerCallback, Handler)) this account must have, null for none
addAccountOptions Authenticator-specific options for the request, may be null or empty
activity The Activity context to use for launching a new authenticator-defined sub-Activity to prompt the user to create an account; used only to call startActivity(); if null, the prompt will not be launched directly, but the necessary Intent will be returned to the caller instead
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns
  • An AccountManagerFuture which resolves to a Bundle with these fields if activity was specified and an account was created: If no activity was specified, the returned Bundle contains only KEY_INTENT with the Intent needed to launch the actual account creation process. If an error occurred, getResult() throws:
    • AuthenticatorException if no authenticator was registered for this account type or the authenticator failed to respond
    • OperationCanceledException if the operation was canceled for any reason, including the user canceling the creation process
    • IOException if the authenticator experienced an I/O problem creating a new account, usually because of network trouble

public boolean addAccountExplicitly (Account account, String password, Bundle userdata)

Since: API Level 5

Adds an account directly to the AccountManager. Normally used by sign-up wizards associated with authenticators, not directly by applications.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission AUTHENTICATE_ACCOUNTS and to have the same UID as the added account's authenticator.

Parameters
account The Account to add
password The password to associate with the account, null for none
userdata String values to use for the account's userdata, null for none
Returns
  • True if the account was successfully added, false if the account already exists, the account is null, or another error occurs.

public void addOnAccountsUpdatedListener (OnAccountsUpdateListener listener, Handler handler, boolean updateImmediately)

Since: API Level 5

Adds an OnAccountsUpdateListener to this instance of the AccountManager. This listener will be notified whenever the list of accounts on the device changes.

As long as this listener is present, the AccountManager instance will not be garbage-collected, and neither will the Context used to retrieve it, which may be a large Activity instance. To avoid memory leaks, you must remove this listener before then. Normally listeners are added in an Activity or Service's onCreate(Bundle) and removed in onDestroy().

It is safe to call this method from the main thread.

No permission is required to call this method.

Parameters
listener The listener to send notifications to
handler Handler identifying the thread to use for notifications, null for the main thread
updateImmediately If true, the listener will be invoked (on the handler thread) right away with the current account list
Throws
IllegalArgumentException if listener is null
IllegalStateException if listener was already added

public String blockingGetAuthToken (Account account, String authTokenType, boolean notifyAuthFailure)

Since: API Level 5

This convenience helper synchronously gets an auth token with getAuthToken(Account, String, boolean, AccountManagerCallback, Handler).

This method may block while a network request completes, and must never be made from the main thread.

This method requires the caller to hold the permission USE_CREDENTIALS.

Parameters
account The account to fetch an auth token for
authTokenType The auth token type, see {#link getAuthToken}
notifyAuthFailure If true, display a notification and return null if authentication fails; if false, prompt and wait for the user to re-enter correct credentials before returning
Returns
  • An auth token of the specified type for this account, or null if authentication fails or none can be fetched.
Throws
AuthenticatorException if the authenticator failed to respond
OperationCanceledException if the request was canceled for any reason, including the user canceling a credential request
IOException if the authenticator experienced an I/O problem creating a new auth token, usually because of network trouble

public void clearPassword (Account account)

Since: API Level 5

Forgets a saved password. This erases the local copy of the password; it does not change the user's account password on the server. Has the same effect as setPassword(account, null) but requires fewer permissions, and may be used by applications or management interfaces to "sign out" from an account.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission MANAGE_ACCOUNTS

Parameters
account The account whose password to clear

public AccountManagerFuture<Bundle> confirmCredentials (Account account, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)

Since: API Level 5

Confirms that the user knows the password for an account to make extra sure they are the owner of the account. The user-entered password can be supplied directly, otherwise the authenticator for this account type prompts the user with the appropriate interface. This method is intended for applications which want extra assurance; for example, the phone lock screen uses this to let the user unlock the phone with an account password if they forget the lock pattern.

If the user-entered password matches a saved password for this account, the request is considered valid; otherwise the authenticator verifies the password (usually by contacting the server).

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission MANAGE_ACCOUNTS.

Parameters
account The account to confirm password knowledge for
options Authenticator-specific options for the request; if the KEY_PASSWORD string field is present, the authenticator may use it directly rather than prompting the user; may be null or empty
activity The Activity context to use for launching a new authenticator-defined sub-Activity to prompt the user to enter a password; used only to call startActivity(); if null, the prompt will not be launched directly, but the necessary Intent will be returned to the caller instead
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns

public AccountManagerFuture<Bundle> editProperties (String accountType, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)

Since: API Level 5

Offers the user an opportunity to change an authenticator's settings. These properties are for the authenticator in general, not a particular account. Not all authenticators support this method.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission MANAGE_ACCOUNTS.

Parameters
accountType The account type associated with the authenticator to adjust
activity The Activity context to use for launching a new authenticator-defined sub-Activity to adjust authenticator settings; used only to call startActivity(); if null, the settings dialog will not be launched directly, but the necessary Intent will be returned to the caller instead
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns
  • An AccountManagerFuture which resolves to a Bundle which is empty if properties were edited successfully, or if no activity was specified, contains only KEY_INTENT needed to launch the authenticator's settings dialog. If an error occurred, getResult() throws:
    • AuthenticatorException if no authenticator was registered for this account type or the authenticator failed to respond
    • OperationCanceledException if the operation was canceled for any reason, including the user canceling the settings dialog
    • IOException if the authenticator experienced an I/O problem updating settings, usually because of network trouble

public static AccountManager get (Context context)

Since: API Level 5

Gets an AccountManager instance associated with a Context. The Context will be used as long as the AccountManager is active, so make sure to use a Context whose lifetime is commensurate with any listeners registered to addOnAccountsUpdatedListener(OnAccountsUpdateListener, Handler, boolean) or similar methods.

It is safe to call this method from the main thread.

No permission is required to call this method.

Parameters
context The Context to use when necessary
Returns

public Account[] getAccounts ()

Since: API Level 5

Lists all accounts of any type registered on the device. Equivalent to getAccountsByType(null).

It is safe to call this method from the main thread.

This method requires the caller to hold the permission GET_ACCOUNTS.

Returns
  • An array of Account, one for each account. Empty (never null) if no accounts have been added.

public Account[] getAccountsByType (String type)

Since: API Level 5

Lists all accounts of a particular type. The account type is a string token corresponding to the authenticator and useful domain of the account. For example, there are types corresponding to Google and Facebook. The exact string token to use will be published somewhere associated with the authenticator in question.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission GET_ACCOUNTS.

Parameters
type The type of accounts to return, null to retrieve all accounts
Returns
  • An array of Account, one per matching account. Empty (never null) if no accounts of the specified type have been added.

public AccountManagerFuture<Account[]> getAccountsByTypeAndFeatures (String type, String[] features, AccountManagerCallback<Account[]> callback, Handler handler)

Since: API Level 5

Lists all accounts of a type which have certain features. The account type identifies the authenticator (see getAccountsByType(String)). Account features are authenticator-specific string tokens identifying boolean account properties (see hasFeatures(Account, String[], AccountManagerCallback, Handler)).

Unlike getAccountsByType(String), this method calls the authenticator, which may contact the server or do other work to check account features, so the method returns an AccountManagerFuture.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission GET_ACCOUNTS.

Parameters
type The type of accounts to return, must not be null
features An array of the account features to require, may be null or empty
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns
  • An AccountManagerFuture which resolves to an array of Account, one per account of the specified type which matches the requested features.

public AccountManagerFuture<Bundle> getAuthToken (Account account, String authTokenType, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)

Since: API Level 5

Gets an auth token of the specified type for a particular account, prompting the user for credentials if necessary. This method is intended for applications running in the foreground where it makes sense to ask the user directly for a password.

If a previously generated auth token is cached for this account and type, then it is returned. Otherwise, if a saved password is available, it is sent to the server to generate a new auth token. Otherwise, the user is prompted to enter a password.

Some authenticators have auth token types, whose value is authenticator-dependent. Some services use different token types to access different functionality -- for example, Google uses different auth tokens to access Gmail and Google Calendar for the same account.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission USE_CREDENTIALS.

Parameters
account The account to fetch an auth token for
authTokenType The auth token type, an authenticator-dependent string token, must not be null
options Authenticator-specific options for the request, may be null or empty
activity The Activity context to use for launching a new authenticator-defined sub-Activity to prompt the user for a password if necessary; used only to call startActivity(); must not be null.
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns
  • An AccountManagerFuture which resolves to a Bundle with at least the following fields: (Other authenticator-specific values may be returned.) If an auth token could not be fetched, getResult() throws:
    • AuthenticatorException if the authenticator failed to respond
    • OperationCanceledException if the operation is canceled for any reason, incluidng the user canceling a credential request
    • IOException if the authenticator experienced an I/O problem creating a new auth token, usually because of network trouble
    If the account is no longer present on the device, the return value is authenticator-dependent. The caller should verify the validity of the account before requesting an auth token.

public AccountManagerFuture<Bundle> getAuthToken (Account account, String authTokenType, boolean notifyAuthFailure, AccountManagerCallback<Bundle> callback, Handler handler)

Since: API Level 5

Gets an auth token of the specified type for a particular account, optionally raising a notification if the user must enter credentials. This method is intended for background tasks and services where the user should not be immediately interrupted with a password prompt.

If a previously generated auth token is cached for this account and type, then it is returned. Otherwise, if a saved password is available, it is sent to the server to generate a new auth token. Otherwise, an Intent is returned which, when started, will prompt the user for a password. If the notifyAuthFailure parameter is set, a status bar notification is also created with the same Intent, alerting the user that they need to enter a password at some point.

In that case, you may need to wait until the user responds, which could take hours or days or forever. When the user does respond and supply a new password, the account manager will broadcast the LOGIN_ACCOUNTS_CHANGED_ACTION Intent, which applications can use to try again.

If notifyAuthFailure is not set, it is the application's responsibility to launch the returned Intent at some point. Either way, the result from this call will not wait for user action.

Some authenticators have auth token types, whose value is authenticator-dependent. Some services use different token types to access different functionality -- for example, Google uses different auth tokens to access Gmail and Google Calendar for the same account.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission USE_CREDENTIALS.

Parameters
account The account to fetch an auth token for
authTokenType The auth token type, an authenticator-dependent string token, must not be null
notifyAuthFailure True to add a notification to prompt the user for a password if necessary, false to leave that to the caller
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns
  • An AccountManagerFuture which resolves to a Bundle with at least the following fields on success: (Other authenticator-specific values may be returned.) If the user must enter credentials, the returned Bundle contains only KEY_INTENT with the Intent needed to launch a prompt. If an error occurred, getResult() throws:
    • AuthenticatorException if the authenticator failed to respond
    • OperationCanceledException if the operation is canceled for any reason, incluidng the user canceling a credential request
    • IOException if the authenticator experienced an I/O problem creating a new auth token, usually because of network trouble
    If the account is no longer present on the device, the return value is authenticator-dependent. The caller should verify the validity of the account before requesting an auth token.

public AccountManagerFuture<Bundle> getAuthTokenByFeatures (String accountType, String authTokenType, String[] features, Activity activity, Bundle addAccountOptions, Bundle getAuthTokenOptions, AccountManagerCallback<Bundle> callback, Handler handler)

Since: API Level 5

This convenience helper combines the functionality of getAccountsByTypeAndFeatures(String, String[], AccountManagerCallback, Handler), getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler), and addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback, Handler).

This method gets a list of the accounts matching the specified type and feature set; if there is exactly one, it is used; if there are more than one, the user is prompted to pick one; if there are none, the user is prompted to add one. Finally, an auth token is acquired for the chosen account.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission MANAGE_ACCOUNTS.

Parameters
accountType The account type required (see getAccountsByType(String)), must not be null
authTokenType The desired auth token type (see getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler)), must not be null
features Required features for the account (see getAccountsByTypeAndFeatures(String, String[], AccountManagerCallback, Handler)), may be null or empty
activity The Activity context to use for launching new sub-Activities to prompt to add an account, select an account, and/or enter a password, as necessary; used only to call startActivity(); should not be null
addAccountOptions Authenticator-specific options to use for adding new accounts; may be null or empty
getAuthTokenOptions Authenticator-specific options to use for getting auth tokens; may be null or empty
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns

public AuthenticatorDescription[] getAuthenticatorTypes ()

Since: API Level 5

Lists the currently registered authenticators.

It is safe to call this method from the main thread.

No permission is required to call this method.

Returns
  • An array of AuthenticatorDescription for every authenticator known to the AccountManager service. Empty (never null) if no authenticators are known.

public String getPassword (Account account)

Since: API Level 5

Gets the saved password associated with the account. This is intended for authenticators and related code; applications should get an auth token instead.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission AUTHENTICATE_ACCOUNTS and to have the same UID as the account's authenticator.

Parameters
account The account to query for a password
Returns
  • The account's password, null if none or if the account doesn't exist

public String getUserData (Account account, String key)

Since: API Level 5

Gets the user data named by "key" associated with the account. This is intended for authenticators and related code to store arbitrary metadata along with accounts. The meaning of the keys and values is up to the authenticator for the account.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission AUTHENTICATE_ACCOUNTS and to have the same UID as the account's authenticator.

Parameters
account The account to query for user data
Returns
  • The user data, null if the account or key doesn't exist

public AccountManagerFuture<Boolean> hasFeatures (Account account, String[] features, AccountManagerCallback<Boolean> callback, Handler handler)

Since: API Level 8

Finds out whether a particular account has all the specified features. Account features are authenticator-specific string tokens identifying boolean account properties. For example, features are used to tell whether Google accounts have a particular service (such as Google Calendar or Google Talk) enabled. The feature names and their meanings are published somewhere associated with the authenticator in question.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission GET_ACCOUNTS.

Parameters
account The Account to test
features An array of the account features to check
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns
  • An AccountManagerFuture which resolves to a Boolean, true if the account exists and has all of the specified features.

public void invalidateAuthToken (String accountType, String authToken)

Since: API Level 5

Removes an auth token from the AccountManager's cache. Does nothing if the auth token is not currently in the cache. Applications must call this method when the auth token is found to have expired or otherwise become invalid for authenticating requests. The AccountManager does not validate or expire cached auth tokens otherwise.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission MANAGE_ACCOUNTS or USE_CREDENTIALS

Parameters
accountType The account type of the auth token to invalidate, must not be null
authToken The auth token to invalidate, may be null

public String peekAuthToken (Account account, String authTokenType)

Since: API Level 5

Gets an auth token from the AccountManager's cache. If no auth token is cached for this account, null will be returned -- a new auth token will not be generated, and the server will not be contacted. Intended for use by the authenticator, not directly by applications.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission AUTHENTICATE_ACCOUNTS and to have the same UID as the account's authenticator.

Parameters
account The account to fetch an auth token for
authTokenType The type of auth token to fetch, see {#getAuthToken}
Returns
  • The cached auth token for this account and type, or null if no auth token is cached or the account does not exist.

public AccountManagerFuture<Boolean> removeAccount (Account account, AccountManagerCallback<Boolean> callback, Handler handler)

Since: API Level 5

Removes an account from the AccountManager. Does nothing if the account does not exist. Does not delete the account from the server. The authenticator may have its own policies preventing account deletion, in which case the account will not be deleted.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission MANAGE_ACCOUNTS.

Parameters
account The Account to remove
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns
  • An AccountManagerFuture which resolves to a Boolean, true if the account has been successfully removed, false if the authenticator forbids deleting this account.

public void removeOnAccountsUpdatedListener (OnAccountsUpdateListener listener)

Since: API Level 5

Removes an OnAccountsUpdateListener previously registered with addOnAccountsUpdatedListener(OnAccountsUpdateListener, Handler, boolean). The listener will no longer receive notifications of account changes.

It is safe to call this method from the main thread.

No permission is required to call this method.

Parameters
listener The previously added listener to remove
Throws
IllegalArgumentException if listener is null
IllegalStateException if listener was not already added

public void setAuthToken (Account account, String authTokenType, String authToken)

Since: API Level 5

Adds an auth token to the AccountManager cache for an account. If the account does not exist then this call has no effect. Replaces any previous auth token for this account and auth token type. Intended for use by the authenticator, not directly by applications.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission AUTHENTICATE_ACCOUNTS and to have the same UID as the account's authenticator.

Parameters
account The account to set an auth token for
authTokenType The type of the auth token, see {#getAuthToken}
authToken The auth token to add to the cache

public void setPassword (Account account, String password)

Since: API Level 5

Sets or forgets a saved password. This modifies the local copy of the password used to automatically authenticate the user; it does not change the user's account password on the server. Intended for use by the authenticator, not directly by applications.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission AUTHENTICATE_ACCOUNTS and have the same UID as the account's authenticator.

Parameters
account The account to set a password for
password The password to set, null to clear the password

public void setUserData (Account account, String key, String value)

Since: API Level 5

Sets one userdata key for an account. Intended by use for the authenticator to stash state for itself, not directly by applications. The meaning of the keys and values is up to the authenticator.

It is safe to call this method from the main thread.

This method requires the caller to hold the permission AUTHENTICATE_ACCOUNTS and to have the same UID as the account's authenticator.

Parameters
account The account to set the userdata for
key The userdata key to set. Must not be null
value The value to set, null to clear this userdata key

public AccountManagerFuture<Bundle> updateCredentials (Account account, String authTokenType, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)

Since: API Level 5

Asks the user to enter a new password for an account, updating the saved credentials for the account. Normally this happens automatically when the server rejects credentials during an auth token fetch, but this can be invoked directly to ensure we have the correct credentials stored.

This method may be called from any thread, but the returned AccountManagerFuture must not be used on the main thread.

This method requires the caller to hold the permission MANAGE_ACCOUNTS.

Parameters
account The account to update credentials for
authTokenType The credentials entered must allow an auth token of this type to be created (but no actual auth token is returned); may be null
options Authenticator-specific options for the request; may be null or empty
activity The Activity context to use for launching a new authenticator-defined sub-Activity to prompt the user to enter a password; used only to call startActivity(); if null, the prompt will not be launched directly, but the necessary Intent will be returned to the caller instead
callback Callback to invoke when the request completes, null for no callback
handler Handler identifying the callback thread, null for the main thread
Returns
  • An AccountManagerFuture which resolves to a Bundle with these fields if an activity was supplied and the account credentials were successfully updated: If no activity was specified, the returned Bundle contains only KEY_INTENT with the Intent needed to launch the password prompt. If an error occurred, getResult() throws:
    • AuthenticatorException if the authenticator failed to respond
    • OperationCanceledException if the operation was canceled for any reason, including the user canceling the password prompt
    • IOException if the authenticator experienced an I/O problem verifying the password, usually because of network trouble