Server Reference

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

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: Bearer <access_token>. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the Authorization header. For more information on obtaining this token, see Provide credentials manually.
  • access_token_auth: true. Set this parameter in the header.
  • [optional] boolean details: set this query parameter to true to get FCM topic subscription information (if any) 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.
  • platform - returns ANDROID, IOS, or CHROME to indicate the device platform to which the token belongs.

If the details flag is set:

  • 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
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

Example result

HTTP 200 OK
{
  "application":"com.iid.example",
  "authorizedEntity":"123456782354",
  "platform":"Android",
  "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 an FCM 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 an FCM 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: Bearer <access_token>. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the Authorization header. For more information on obtaining this token, see Provide credentials manually.
  • access_token_auth: true. 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: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true

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 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: Bearer <access_token>. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the Authorization header. For more information on obtaining this token, see Provide credentials manually.
  • access_token_auth: true. 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.
  • RESOURCE_EXHAUSTED — Too many subscription or unsubscription requests in a short period of time. Retry with exponential backoff.

Example POST request

https://iid.googleapis.com/iid/v1:batchAdd
Content-Type:application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth: true
{
   "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 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 messages to the corresponding APNs device token.

Parameters

  • Authorization: Bearer <access_token>. Set this parameter in the header. Add a short-lived OAuth2 token as the value of the Authorization header. For more information on obtaining this token, see Provide credentials manually.
  • access_token_auth: true. 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 maps to the APNs token.

Example POST request

https://iid.googleapis.com/iid/v1:batchImport
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
access_token_auth:true
{
  "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"
        },
     ]
  }

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.