Generate access tokens

This page describes the production deployment authorization flow introduced in Authorization. In this flow, your backend uses a service account API key to request short-lived access tokens for authenticated users, then returns those tokens to the client for use with NSDK.

Unlike developer tokens, these access tokens are short-lived, user-scoped, and issued by your backend. Backend integration is required only for production deployment and is not needed when testing with sample apps. To issue these access tokens, your backend uses a service account API key. Service account API keys are secrets that must never be distributed to client applications. Treat your API key like any other sensitive credential and store it securely on your backend.

Production token flow

This workflow applies only to production deployment. For an overview of the full authorization model, including developer tokens and production deployment, see Authorization.

In the production deployment flow, token issuance and use work as follows. This page focuses on the backend token-issuance step.

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. The service account API key stays on your backend and must never be distributed to clients.
3. The backend returns the access token to the client as part of your backend implementation.
4. The client provides the access token to the NSDK. See Passing access tokens to the NSDK.
5. When the token approaches expiration, the client requests a new one from your backend.

Create a service account

Requesting short-lived access tokens for production deployment requires a service account with an associated API key. Keep these credentials secure on your backend server, along with any 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 a business 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.

See Client code integration for additional details.

Request an access token

To obtain a short-lived access token for NSDK, 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: The service account API key created when you set up a service account. Keep this key on your backend.
• NEW_API_KEY_ACCESS_TOKEN: The short-lived 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.