Go to console

Firebase Auth REST API

API Usage

You can query the Firebase Auth backend through a REST API. This can be used for various operations such as creating new users, signing in existing ones and editing or deleting these users.

Throughout this document, API_KEY refers to the Web API Key, which can be obtained on the project settings page in your admin console.

Exchange custom token for an ID and refresh token

You can exchange a custom Auth token for an ID and refresh token by issuing an HTTP POST request to the Auth verifyCustomToken endpoint.

Method: POST

Content-Type: application/json

Endpoint
https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]
Request Body Payload
Property Name Type Description
token string A Firebase Auth custom token from which to create an ID and refresh token pair.
returnSecureToken boolean Whether or not to return an ID and refresh token. Should always be true.
Response Payload
Property Name Type Description
idToken string A Firebase Auth ID token generated from the provided custom token.
refreshToken string A Firebase Auth refresh token generated from the provided custom token.
expiresIn string The number of seconds in which the ID token expires.

Sample request

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"token":"[CUSTOM_TOKEN]","returnSecureToken":true}'

A successful request is indicated by a 200 OK HTTP status code. The response contains the Firebase ID token and refresh token associated with the custom token.

Sample response

{
  "idToken": "[ID_TOKEN]",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600"
}

Common error codes

  • INVALID_CUSTOM_TOKEN: The custom token format is incorrect or the token is invalid for some reason (e.g. expired, invalid signature etc.)
  • CREDENTIAL_MISMATCH: The custom token corresponds to a different Firebase project.

Exchange a refresh token for an ID token

You can refresh a Firebase ID token by issuing an HTTP POST request to the securetoken.googleapis.com endpoint.

Method: POST

Content-Type: application/x-www-form-urlencoded

Endpoint
https://securetoken.googleapis.com/v1/token?key=[API_KEY]
Request Body Payload
Property Name Type Description
grant_type string The refresh token's grant type, always "refresh_token".
refresh_token string A Firebase Auth refresh token.
Response Payload
Property Name Type Description
expires_in string The number of seconds in which the ID token expires.
token_type string The type of the refresh token, always "Bearer".
refresh_token string The Firebase Auth refresh token provided in the request or a new refresh token.
id_token string A Firebase Auth ID token.
user_id string The uid corresponding to the provided ID token.
project_id string Your Firebase project ID.

Sample request

curl 'https://securetoken.googleapis.com/v1/token?key=[API_KEY]' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token&refresh_token=[REFRESH_TOKEN]'

A successful request is indicated by a 200 OK HTTP status code. The response contains the new Firebase ID token and refresh token.

Sample response

{
  "expires_in": "3600",
  "token_type": "Bearer",
  "refresh_token": "[REFRESH_TOKEN]",
  "id_token": "[ID_TOKEN]",
  "user_id": "tRcfmLH7o2XrNELi...",
  "project_id": "1234567890"
}

Common error codes

  • TOKEN_EXPIRED: The user's credential is no longer valid. The user must sign in again.
  • USER_DISABLED: The user account has been disabled by an administrator.
  • USER_NOT_FOUND: The user corresponding to the refresh token was not found. It is likely the user was deleted.
  • API key not valid. Please pass a valid API key. (invalid API key provided)
  • INVALID_REFRESH_TOKEN: An invalid refresh token is provided.
  • Invalid JSON payload received. Unknown name \"refresh_tokens\": Cannot bind query parameter. Field 'refresh_tokens' could not be found in request message.
  • INVALID_GRANT_TYPE: the grant type specified is invalid.
  • MISSING_REFRESH_TOKEN: no refresh token provided.

Sign up with email / password

You can create a new email and password user by issuing an HTTP POST request to the Auth signupNewUser endpoint.

Method: POST

Content-Type: application/json

Endpoint
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]
Request Body Payload
Property Name Type Description
email string The email for the user to create.
password string The password for the user to create.
returnSecureToken boolean Whether or not to return an ID and refresh token. Should always be true.
Response Payload
Property Name Type Description
idToken string A Firebase Auth ID token for the newly created user.
email string The email for the newly created user.
refreshToken string A Firebase Auth refresh token for the newly created user.
expiresIn string The number of seconds in which the ID token expires.
localId string The uid of the newly created user.

Sample request

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"email":"[user@example.com]","password":"[PASSWORD]","returnSecureToken":true}'

A successful request is indicated by a 200 OK HTTP status code. The response contains the Firebase ID token and refresh token associated with the new account.

Sample response

{
  "idToken": "[ID_TOKEN]",
  "email": "[user@example.com]",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "localId": "tRcfmLH7..."
}

Common error codes

  • EMAIL_EXISTS: The email address is already in use by another account.
  • OPERATION_NOT_ALLOWED: Password sign-in is disabled for this project.
  • TOO_MANY_ATTEMPTS_TRY_LATER: We have blocked all requests from this device due to unusual activity. Try again later.

Sign in with email / password

You can sign in a user with an email and password by issuing an HTTP POST request to the Auth verifyPassword endpoint.

Method: POST

Content-Type: application/json

Endpoint
https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=[API_KEY]
Request Body Payload
Property Name Type Description
email string The email the user is signing in with.
password string The password for the account.
returnSecureToken boolean Whether or not to return an ID and refresh token. Should always be true.
Response Payload
Property Name Type Description
idToken string A Firebase Auth ID token for the authenticated user.
email string The email for the authenticated user.
refreshToken string A Firebase Auth refresh token for the authenticated user.
expiresIn string The number of seconds in which the ID token expires.
localId string The uid of the authenticated user.
registered boolean Whether the email is for an existing account.

Sample request

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=[API_KEY]' \
-H 'Content-Type: application/json' \
--data-binary '{"email":"[user@example.com]","password":"[PASSWORD]","returnSecureToken":true}'

A successful request is indicated by a 200 OK HTTP status code. The response contains the Firebase ID token and refresh token associated with the existing email/password account.

Sample response

{
  "localId": "ZY1rJK0eYLg...",
  "email": "[user@example.com]",
  "displayName": "",
  "idToken": "[ID_TOKEN]",
  "registered": true,
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600"
}

Common error codes

  • EMAIL_NOT_FOUND: There is no user record corresponding to this identifier. The user may have been deleted.
  • INVALID_PASSWORD: The password is invalid or the user does not have a password.
  • USER_DISABLED: The user account has been disabled by an administrator.

Sign in anonymously

You can sign in a user anonymously by issuing an HTTP POST request to the Auth signupNewUser endpoint.

Method: POST

Content-Type: application/json

Endpoint
https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]
Request Body Payload
Property Name Type Description
returnSecureToken boolean Whether or not to return an ID and refresh token. Should always be true.
Response Payload
Property Name Type Description
idToken string A Firebase Auth ID token for the newly created user.
email string Since the user is anonymous, this should be empty.
refreshToken string A Firebase Auth refresh token for the newly created user.
expiresIn string The number of seconds in which the ID token expires.
localId string The uid of the newly created user.

Sample request

curl 'https://identitytoolkit.googleapis.com/v1/accounts:signUp?key=[API_KEY]' \
-H 'Content-Type: application/json' --data-binary '{"returnSecureToken":true}'

A successful request is indicated by a 200 OK HTTP status code. The response contains the Firebase ID token and refresh token associated with the anonymous user.

Sample response

{
  "idToken": "[ID_TOKEN]",
  "email": "",
  "refreshToken": "[REFRESH_TOKEN]",
  "expiresIn": "3600",
  "localId": "Jws4SVjpT..."
}

Common error codes

  • OPERATION_NOT_ALLOWED: Anonymous user sign-in is disabled for this project.

Sign in with OAuth credential

You can sign in a user with an OAuth credential by issuing an HTTP POST request to the Auth verifyAssertion endpoint.

Method: POST

Content-Type: application/json

Endpoint
https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=[API_KEY]
Request Body Payload
Property Name Type Description
requestUri string The URI to which the IDP redirects the user back.
postBody string Contains the OAuth credential (an ID token or access token) and provider ID which issues the credential.
returnSecureToken boolean Whether or not to return an ID and refresh token. Should always be true.
returnIdpCredential boolean Whether to force the return of the OAuth credential on the following errors: FEDERATED_USER_ID_ALREADY_LINKED and EMAIL_EXISTS.
Response Payload
Property Name Type Description
federatedId string The unique ID identifies the IdP account.
providerId string The linked provider ID (e.g. "google.com" for the Google provider).
localId string The uid of the authenticated user.
emailVerified boolean Whether the sign-in email is verified.
email string The email of the account.
oauthIdToken string The OIDC id token if available.
oauthAccessToken string The OAuth access token if available.
oauthTokenSecret string The OAuth 1.0 token secret if available.
rawUserInfo string The stringified JSON response containing all the IdP data corresponding to the provided OAuth credential.
firstName string The first name for the account.
lastName string The last nam