Server Reference

Server implementation is optional. Use the Instance ID service if you want to perform these operations:

Get information about app instances. Verify app tokens or get more information about the app instance that created the token.
Create relationship maps for app instances. Create relationships between app instances and entities such as FCM or GCM topics.
Create registration tokens for APNs tokens. This API lets you bulk import existing APNs tokens, mapping them to valid registration tokens for FCM or GCM.
Manage registration tokens for push subscriptions. For web applications implemented using the Push API, import your existing push subscriptions, mapping them to valid registration tokens for FCM.

Get information about app instances

To get information about an app instance, call the Instance ID service at this endpoint, providing the app instance's token as shown:

 https://iid.googleapis.com/iid/info/IID_TOKEN

Parameters

Authorization: key=YOUR_API_KEY. Set this parameter in the header.
[optional] boolean details: set this query parameter to true to get available IID token details, including connection information and FCM or GCM topic subscription information (if any) for the device associated with this token. When not specified, defaults to false.

Results

On success the call returns HTTP status 200 and a JSON object containing:

application - package name associated with the token.
authorizedEntity - projectId authorized to send to the token.
applicationVersion - version of the application.
appSigner - sha1 fingerprint for the signature applied to the package. Indicates which party signed the app; for example,Play Store.
attestStatus - returns ROOTED, NOT_ROOTED, or UNKNOWN to indicate whether or not the device is rooted.
platform - returns ANDROID, IOS, or CHROME to indicate the device platform to which the token belongs.

If the details flag is set:

connectionType - returns WIFI, MOBILE or OTHER. Returns nothing if the connection is uninitialized.
connectDate - the most recent day that the device has established a connection with GCM.
rel - relations associated with the token. For example, a list of topic subscriptions.

Example `GET` request

https://iid.googleapis.com/iid/info/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA?details=true
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Example result

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "attestStatus":"ROOTED",
  "appSigner":"1a2bc3d4e5",
  "connectionType":"WIFI",
  "connectDate":"2015-05-12
  "rel":{
    "topics":{
      "topicname1":{"addDate":"2015-07-30"},
      "topicname2":{"addDate":"2015-07-30"},
      "topicname3":{"addDate":"2015-07-30"},
      "topicname4":{"addDate":"2015-07-30"}
    }
  }
}

Create relationship maps for app instances

The Instance ID API lets you create relationship maps for app instances. For example, you can map a registration token to a Google Cloud Messaging topic, subscribing the app instance to the topic. The API provides methods for creating such relationships both individually, and in bulk.

Create a relation mapping for an app instance

Given a registration token and a supported relationship, you can create a mapping. For example, you can subscribe an app instance to a Google Cloud Messaging topic by calling the Instance ID service at this endpoint, providing the app instance's token as shown:

 https://iid.googleapis.com/iid/v1/IID_TOKEN/rel/topics/TOPIC_NAME

Parameters

Authorization: key=YOUR_API_KEY. Set this parameter in the header.

Results

On success the call returns HTTP status 200.

Example `POST` request

https://iid.googleapis.com/iid/v1/nKctODamlM4:CKrh_PC8kIb7O...clJONHoA/rel/topics/movies
Content-Type:application/json
Content-Length: 0
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA

Example result

HTTP 200 OK
{}

Manage relationship maps for multiple app instances

Using the Instance ID service's batch methods, you can perform batch management of app instances. For example, you can perform bulk addition or removal of app instances to an FCM or GCM topic. To update up to 1000 app instances per API call, call the Instance ID service at this endpoint, providing the app instance tokens in the JSON body:

 https://iid.googleapis.com/iid/v1:batchAdd

 https://iid.googleapis.com/iid/v1:batchRemove

Parameters

Authorization: key=YOUR_API_KEY. Set this parameter in the header.
to : The topic name.
registration_tokens : The array of IID tokens for the app instances you want to add or remove.

Results

On success the call returns HTTP status 200. Empty results indicate successful subscription for the token. For failed subscriptions, the result contains one of these error codes:

NOT_FOUND — The registration token has been deleted or the app has been uninstalled.
INVALID_ARGUMENT — The registration token provided is not valid for the Sender ID.
INTERNAL — The backend server failed for unknown reasons. Retry the request.
TOO_MANY_TOPICS — Excessive number of topics per app instance.

Example `POST` request

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization:key=API_KEY
{
   "to": "/topics/movies",
   "registration_tokens": ["nKctODamlM4:CKrh_PC8kIb7O...", "1uoasi24:9jsjwuw...", "798aywu:cba420..."],
}

Example result

HTTP 200 OK
{
  "results":[
    {},
    {"error":"NOT_FOUND"},
    {},
  ]
}

Create registration tokens for APNs tokens

Using the Instance ID service's batchImport method, you can bulk import existing iOS APNs tokens to Google Cloud Messaging or Firebase Cloud Messaging, mapping them to valid registration tokens. Call the Instance ID service at this endpoint, providing a list of APNs tokens in the JSON body:

 https://iid.googleapis.com/iid/v1:batchImport

The response body contains an array of Instance ID registration tokens ready to be used for sending FCM or GCM messages to the corresponding APNs device token.

Parameters

Authorization: key=YOUR_API_KEY. Set this parameter in the header.
application : Bundle id of the app.
sandbox : Boolean to indicate sandbox environment (TRUE) or production (FALSE)
apns_tokens : The array of APNs tokens for the app instances you want to add or remove. Maximum 100 tokens per request.

Results

On success the call returns HTTP status 200 and a JSON result body. For each APNs token provided in the request, the results list includes:

The APNs token.
Status. Either OK, or an error message describing the failure.
For successful results, the registration token that FCM or GCM maps to the APNs token.

Example `POST` request

https://iid.googleapis.com/iid/v1:batchImport
{
  "application": "com.google.FCMTestApp",
  "sandbox":false,
  "apns_tokens":[
      "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
      "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86"
   ]
  }
}

Example result

HTTP 200 OK
{
 "results":[
       {
        "apns_token": "368dde283db539abc4a6419b1795b6131194703b816e4f624ffa12",
         "status": "OK",
         "registration_token":"nKctODamlM4:CKrh_PC8kIb7O...clJONHoA"
       },
       {
         "apns_token": "76b39c2b2ceaadee8400b8868c2f45325ab9831c1998ed70859d86",
         "status":"Internal Server Error"
        },
     ]
  }

Manage registration tokens for push subscriptions

Using the Instance ID service's Web methods, you can import existing push subscriptions for Firebase Cloud Messaging. You can also update and delete them.

When you import a push subscription, you receive a registration token. This token allows you to use FCM features like topic messaging and device group messaging to target notifications to your web apps.

Import push subscriptions

You can import push subscriptions using InstanceID's web endpoint:

 https://iid.googleapis.com/v1/web/iid

The request must contain an authorization header set to an OAuth 2.0 access token, a crypto-key header set to your application server key, and the PushSubscription object in the request body.

The response body contains a registration token ready to be used for sending FCM or GCM messages to the corresponding web app instance without having to encrypt the payload.

Upload your VAPID key pair to the console

To import keys, you must have owner-level access to the Firebase project. Import your existing public and private key in base64 URL safe encoded form:

Open the Cloud Messaging tab of the Firebase Console Settings pane and scroll to the Web configuration section.
In the Web Push certificates tab, find and select the link text, "import an existing key pair."
In the Import a key pair dialog, provide your public and private keys in the corresponding fields and click Import. The console displays the public key string and date added.

Retrieve an OAuth2 token: Use credentials to mint access tokens

In order to create an access token for the request, you'll need to mint the access token and add it to the HTTP request.

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    var key = require('./service-account.json');
    var jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}index.js

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_tokenconfigure.py

Java

private static String getAccessToken() throws IOException {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}Configure.java

To authorize access to FCM, request the scope https://www.googleapis.com/auth/firebase.messaging.

Parameters

Authorization: Bearer <access_token>. Set this parameter in the header.
Crypto-Key: p256ecdsa=APPLICATION_PUBLIC_KEY. Set this parameter in the header.
Request body: PushSubscription.toJson(). Pass the push subscription to the HTTP body without parsing it. The content matches W3C encoding of PushSubscription.

Response

On success the call returns HTTP status 200 OK and a JSON result body containing the IID token.

Example `POST` request

 https://iid.googleapis.com/v1/web/iid
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

Example result

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Update push subscriptions

You can update the push subscription associated with your registration token using the following endpoint:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN:refresh

Parameters

Authorization: Bearer <access_token>. Set this parameter in the header.
Crypto-Key: p256ecdsa=APPLICATION_PUBLIC_KEY. Set this parameter in the header.
Request body: PushSubscription.toJson(). Pass the push subscription to the HTTP body without parsing it. The content matches W3C encoding of PushSubscription.

Results

On success the call returns HTTP status 200 and a registration token. This may be the same token you passed in the request, or a new token.

HTTP 200 OK
{
 "token":"KctODamlM4:CKrh_PC...cl"
}

Example `POST` request

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CKrh_PC...cl:refresh
 Content-Type:application/json
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
 Crypto-Key:p256ecdsa=BFv5XHxdkZgpQzCb-...8uI42kf4A4USEIMo
 {
   "endpoint": "https://fcm.googleapis.com/fcm/send/dS4xerbSlqU:APb...aRs4QP",
   "keys": {
         "auth": "7cdY...xxjwz46Q"",
         "p256dh": "BH7xPjScJe...z9lbIZDmOV_c"
    }
 }

Example result

 HTTP 200 OK
 {
  "token":"KctODamlM4:CI2k_HHw...3P1"
 }

Delete push subscriptions

A DELETE request removes the push subscription details from FCM database. You can still receive messages in your web application using the Push API protocol.

To delete a push subscription, send a DELETE request to:

 https://iid.googleapis.com/v1/web/iid/REGISTRATION_TOKEN

Example `DELETE` request

 https://iid.googleapis.com/v1/web/iid/KctODamlM4:CI2k_HHw...3P1
 Authorization:Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

Example result

 HTTP 200 OK {}

Error responses

Calls to the Instance ID server API return the following HTTP error codes:

HTTP status 400 (Bad request) - request parameters are missing or invalid. Check error messages for detailed information.
HTTP status 401 (Unauthorized) - authorization header is invalid.
HTTP status 403 (Forbidden) - authorization header doesn't match the authorizedEntity.
HTTP status 404 (Not found) - Invalid HTTP path or IID token not found. Check error messages for detailed information.
HTTP status 503 (Service unavailable) - service is unavailable. Retry the request with exponential backoff.

Server Reference

Get information about app instances

Parameters

Results

Example GET request

Example result

Create relationship maps for app instances

Create a relation mapping for an app instance

Parameters

Results

Example POST request

Example result

Manage relationship maps for multiple app instances

Parameters

Results

Example POST request

Example result

Create registration tokens for APNs tokens

Parameters

Results

Example POST request

Example result

Manage registration tokens for push subscriptions

Import push subscriptions

Upload your VAPID key pair to the console

Retrieve an OAuth2 token: Use credentials to mint access tokens

node.js

Python

Java

Parameters

Response

Example POST request

Example result

Update push subscriptions

Parameters

Results

Example POST request

Example result

Delete push subscriptions

Example DELETE request

Example result

Error responses

Example `GET` request

Example `POST` request

Example `POST` request

Example `POST` request

Example `POST` request

Example `POST` request

Example `DELETE` request