While the easiest way to useCloud Firestore is to use one of thenative client libraries, there are some situations when it is useful tocall the REST API directly.

The REST API can be helpful for the following use cases:

• AccessingCloud Firestore from a resource-constrained environment,such as an internet of things (IoT) device, where running a complete clientlibrary is not possible.
• Automating database administration or retrieving detailed database metadata.

If you are using agRPC-supported language, consider using theRPC API rather than the REST API.

Authentication and authorization

For authentication, theCloud Firestore REST API accepts either aFirebase Authentication ID token or aGoogle Identity OAuth 2.0 token. The token you provideaffects your request's authorization:

• Use Firebase ID tokens to authenticate requests from your application's users.For these requests,Cloud Firestore usesCloud Firestore Security Rules to determine if a requestis authorized.

• Use a Google Identity OAuth 2.0 token and aservice account to authenticate requests from yourapplication, such as requests for database administration. For these requests,Cloud Firestore usesIdentity and Access Management (IAM) to determine if arequest is authorized.

Working with Firebase ID tokens

You can attain a Firebase ID token in two ways:

• Generate a Firebase ID token using theFirebase Authentication REST API.
• Retrieve a user's Firebase ID token from aFirebase Authentication SDK.

By retrieving a user's Firebase ID token, you can make requests on behalf of theuser.

For requests authenticated with a Firebase ID token and for unauthenticatedrequests,Cloud Firestore uses yourCloud Firestore Security Rules to determine if a request isauthorized.

Working with Google Identity OAuth 2.0 tokens

You can generate an access token by using aservice account with aGoogle API Client Libraryor by following the steps inUsing OAuth 2.0 for Server to Server Applications. Youcan also generate a token with thegcloud command-line tool and thecommandgcloud auth application-default print-access-token.

This token must have the following scope to send requests to theCloud Firestore REST API:

• https://www.googleapis.com/auth/datastore

If you authenticate your requests with a service account and a Google IdentityOAuth 2.0 token,Cloud Firestore assumes that your requests act on behalfof your application instead of an individual user.Cloud Firestore allowsthese requests to ignore your security rules. Instead,Cloud FirestoreusesIAM to determine if a request is authorized.

You can control the access permissions of service accounts by assigningCloud Firestore IAM roles.

Authenticating with an access token

After you obtain either a Firebase ID token or a Google Identity OAuth 2.0token, pass it to theCloud Firestore endpoints as anAuthorizationheader set toBearer {YOUR_TOKEN}.

Making REST calls

All REST API endpoints exist under the base URLhttps://firestore.googleapis.com/v1/.

To create a path to a document with the IDLA in the collectioncitiesunder the projectYOUR_PROJECT_ID you would use the following structure.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

To interact with this path, combine it with the base API URL.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

The best way to begin experimenting with the REST API is to use theAPI Explorer, which automatically generates Google IdentityOAuth 2.0 tokens and allows you to examine the API.

Methods

Below are brief descriptions of the two most important method groups. For a completelist, see theREST API reference or use theAPI Explorer.

v1.projects.databases.documents

Perform CRUD operations on documents, similar to those outlined in theadd data orget data guides.

v1.projects.databases.collectionGroups.indexes

Perform actions on indexes such as creating new indexes, disabling an existingindex, or listing all current indexes. Useful for automating data structuremigrations or synchronizing indexes between projects.

Also enables retrieval of document metadata, such as the list of allfields and subcollections for a given document.

Error Codes

When aCloud Firestore request succeeds, theCloud Firestore API returns an HTTP200 OK status code and therequested data. When a request fails, theCloud Firestore API returns anHTTP4xx or5xx status code and a response with information aboutthe error.

The following table lists recommended actions for each error code. These codes applyto theCloud Firestore REST and RPC APIs. TheCloud FirestoreSDKs and client libraries may not return these same error codes.