Use the ARCore API on Google Cloud

Select platform:

ARCore features such as the Geospatial API and Cloud Anchors use the ARCore API hosted on Google Cloud. When using these features, your application uses credentials to access the ARCore API service.

This quickstart describes how to set up your application so that it can communicate with the ARCore API service hosted on Google Cloud.

Create a new Google Cloud project or use an existing project

If you have an existing project, select it.

Go to project selector

If you don't have an existing Google Cloud project, create one.

Create new project

Enable the ARCore API

To use the ARCore API, you must enable it in your project.

Enable the ARCore API

Set up an authorization method

An iOS application can communicate with the ARCore API using two different authorization methods: Keyless authorization, which is the recommended method, and API Key authorization:

  • Keyless authorization uses a token signed to control access to the API. This method requires a server owned by you to sign tokens and control access to the API.
  • An API key is a string that identifies a Google Cloud project. API keys are generally not considered secure as they are typically accessible to clients. Consider using Token authorization to communicate with the ARCore API.

Keyless

ARCore supports the authorization of API calls in iOS using a (JSON Web token). The token must be signed by a Google Service account.

In order to generate tokens for iOS, you must have an endpoint on your server that satisfies the following requirements:

  • Your own authorization mechanism must protect the endpoint.

  • The endpoint must generate a new token every time, such that:

    • Each user gets a unique token.
    • Tokens don't immediately expire.

Create a service account and signing key

Follow these steps to create a Google service account and signing key:

  1. In Google Cloud, open the Credentials page.
    Credentials
  2. Click Create Credentials > Service account.
  3. Under Service account details, type a name for the new account, then click Create.
  4. On the Service account permissions page, go to the Select a role drop-down. Select Service Accounts > Service Account Token Creator, then click Continue.
  5. On the Grant users access to this service account page, click Done.
  6. On the Credentials page, find the Service Accounts section and click the name of the account you just created.
  7. On the Service account details page, scroll down to the Keys section and select Add Key > Create new key.

  8. Select JSON as the key type and click Create.

    This downloads a JSON file containing the private key to your machine. Store the downloaded JSON key file in a secure location.

Create tokens on your server

To create new tokens (JWTs) on your server, use the standard JWT libraries and the JSON file that you securely downloaded from your new service account.

Create tokens on your development machine

To generate JWTs on your development machine, use the following oauth2l command:

oauth2l fetch --cache "" --jwt --json $KEYFILE --audience "https://arcore.googleapis.com/"

Specifying an empty cache location using the --cache flag is necessary to ensure that a different token is produced each time. Be sure to trim the resulting string. Extra spaces or newline characters will cause the API to reject the token.

Sign the token

You must use the RS256 algorithm and the following claims to sign the JWT:

  • iss — The service account email address.
  • sub — The service account email address.
  • iat — The Unix epoch time when the token was generated, in seconds.
  • exp — iat + 3600 (1 hour). The Unix epoch time when the token expires, in seconds.
  • aud — The audience. It must be set to https://arcore.googleapis.com/.

Non-standard claims are not required in the JWT payload, though you may find the uid claim useful for identifying the corresponding user.

If you use a different approach to generate your JWTs, such as using a Google API in a Google-managed environment, make sure to sign your JWTs with the claims in this section. Above all, make sure that the audience is correct.

Pass the token in the ARCore session

Your app is now configured to use Keyless authentication.

Note the following when you pass a token into the session:

  • If you have used an API key to create the session, ARCore will ignore the token and log an error.

    If you no longer need the API key, delete it in the Google Developers Console and remove it from your app.

  • ARCore ignores tokens that contain spaces or special characters.

  • Tokens typically expire after one hour. If there is a possibility that your token may expire while in use, obtain a new token and pass it to the API.

API Key

  1. In Google Cloud, open the Credentials page.
    Credentials
  2. Click Create credentials, then select API key from the menu.
    The API key created dialog displays the string for your newly created key.
  4. Review documentation on API key restrictions to secure your API key.

Your app is now configured to use API keys.

What's next

With authorization configured, check out the following ARCore features that use it: