Backend integration

The Niantic Spatial Identity Service allows your backend to authorize users to access Niantic Spatial Platform features. This integration is required only for production applications and is not needed when testing with the sample apps.

Production flow

For an overview of the full production and sample token flows, see Access. This workflow applies only to Production applications. See the Access guide for testing or Client code integration for proof of concept flows. In production, your backend handles token issuance and delivery to the client as follows:

1. The client authenticates with your app and requests an access token from your backend.
2. Your backend uses a service account API key to request a short-lived access token by calling the Niantic Spatial Identity Service.
3. The backend returns the access token to the client.
4. The client provides the access token to the NSDK.
5. When the token approaches expiration, the client requests a new one from your backend.

Create a service account

Requesting Niantic Spatial access tokens requires a service account with an associated API key. Keep these credentials secure on your backend server, along with any access token request logic. You can create a service account, which creates a new API key as follows:

1. Log in to your business account in the Scaniverse web. If you don't have a Niantic business account, follow the steps in Create account to create one.
2. Select Service accounts from the left navigation bar.
3. Select New service account in the top right section of the main window.
4. Enter a name for your service account.
5. Select Create.
6. Select the copy icon to copy the API key in the green box to your clipboard.
7. Paste the API key securely into your backend configuration such as an environment variable, config file, or secrets manager. Do not paste it into client code.

Request an access token

To obtain a Niantic Spatial access token, your backend server must make an HTTP request to the Spatial Identity Service as follows:

• Method: POST
• Token endpoint URL: https://spatial-identity.nianticspatial.com/oauth/token
• Body (JSON):

{
    "grantType": "exchange_api_key_access_token",
    "apiKey": {API_KEY}
}

• Expected response (JSON):

{
    "accessToken": {NEW_API_KEY_ACCESS_TOKEN},
    "expiresAt": {EXPIRATION_TIMESTAMP_IN_SECONDS}
}

In the previous request and response:

• API_KEY : Created when you set up a service account.
• NEW_API_KEY_ACCESS_TOKEN: The JSON Web Token (JWT) your backend sends to the client to authorize NSDK access.
• EXPIRATION_TIMESTAMP_IN_SECONDS: Provided by the Niantic Spatial Identity Service to tell you when the access token expires, in seconds since the Unix epoch. Your backend uses this timestamp to know when to request a new token.

Security guidelines

The API key identifies your project and allows your backend to request short-lived access tokens from Niantic Spatial Identity Service. To keep your project and users secure, follow these guidelines:

• API keys must remain confidential and must never be embedded in client applications.
• Clients must request new tokens from your backend rather than refreshing them directly.