Using the REST API

This document shows you how to perform common user operations, such as signing in users and working with tokens, using the Identity Platform REST API.

Before you begin

To use the REST API, you'll need an Identity Platform API key. To obtain a key:

Go to the Identity Providers page in the Google Cloud console.
Go to the Identity Providers page
Click Application setup details.
Copy the apiKey field.

Note that HTTPS is required for all API calls.

Calling the API

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 signInWithCustomToken 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	An Identity Platform 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.
tenantId	string	The tenant ID the user is signing into. Only used in multi-tenancy. Must match the tenant_id in the token.

Custom Token Claims

Property	Name	Description
alg	Algorithm	Should be `RS256`.
iss	Issuer	Your project's service account email address.
sub	Subject	Your project's service account email address.
aud	Audience	`https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit`
iat	Issued-at time	The current time, in seconds since the UNIX epoch.
exp	Expiration time	The time, in seconds since the UNIX epoch, at which the token expires. It can be a maximum of 3600 seconds later than the `iat`. Note: this only controls the time when the custom token itself expires. But once you sign a user in using `signInWithCustomToken()`, they will remain signed in into the device until their session is invalidated or the user signs out.
uid	User Id	The unique identifier of the user, between 1-36 characters long.
tenant_id	Tenant Id	The identifier of the tenant that the user is signing in to.
claims (optional)		Optional custom claims to include in the Security Rules `auth` or `request.auth` variables.

Response Payload

Property Name	Type	Description
idToken	string	An Identity Platform ID token generated from the provided custom token.
refreshToken	string	An Identity Platform 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}'

In the example above, you would replace [API_KEY] with the Web API Key of your Identity Platform project, [CUSTOM_TOKEN] with the generated custom Auth token.

A successful request is indicated by a 200 OK HTTP status code. The response contains the Identity Platform 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 Google Cloud project.

Exchange a refresh token for an ID token

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

Note: By default, Google validates the project number of your refresh token to ensure it matches that of your API key. If the project number doesn't match, you will receive the PROJECT_NUMBER_MISMATCH error code. This validation mitigates the potential risk of abusers collecting your API keys to generate refresh tokens for their own projects. If you understand the risk and want to opt out of this behavior, you can submit an exemption request by filing a Google Cloud support case.

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	An Identity Platform 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 Identity Platform refresh token provided in the request or a new refresh token.
id_token	string	An Identity Platform ID token.
user_id	string	The uid corresponding to the provided ID token.
project_id	string	Your Google Cloud 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]'

In the example above, you would replace [API_KEY] with the Web API Key of your Identity Platform Google Cloud project, [REFRESH_TOKEN] with the Identity Platform refresh token.

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

Sample response

{
  "expires_in": "3600",
  "token_type": "Bearer",
  "refresh_token": "[REFRESH_TOKEN]",
  "id_token"