Authentication
Client keys and secret keys: which ReactVision Studio API key to use where, and how legacy keys move over.
The ReactVision API serves a ReactVision Studio team's cloud anchors, geospatial anchors, uploaded files, Studio scenes and projects, scene API requests, AI generation and co-location rooms. Every request authenticates with an API key. In a ViroReact app you set that key as rvApiKey, and the ID of its project as rvProjectId.
Just getting started?
Create a Studio account, team and project, and copy the project ID, with Getting Started with ReactVision Spatial. Then create a client key as described in Client Keys.
Credentials
There are three credentials:
| Credential | Prefix | Where it belongs | What it reaches |
|---|---|---|---|
| Client key | rv_client_ (rv_live_ for a key converted from legacy) | Inside your app, as rvApiKey. Anyone who has the app can read it, so treat it as public. | One project, chosen when the key is created. |
| Secret key | rv_secret_ | On your own backend, or in an internal build for a demo. Never in an app you publish. Studio shows it once, when it is created. | Every project of the team, or one project if you bind it to one when you create it. |
| User token | rv_ut_ | Minted by your backend with a secret key for one signed-in app user, and handed to that user's app. Lasts up to one hour. | One project and one app user. See User tokens. |
- Client key: hosts, resolves and finds anchors, uploads anchor files, loads Studio scenes and projects, runs a scene's API requests and uses co-location rooms. See Client Keys.
- Secret key: also lists, edits and deletes anchors, uploads images, videos and 3D models, reads and deletes app users' files, runs AI generation and mints user tokens. See Secret Keys.
Never put a secret key in an app you publish, a web page, or anything else you ship. Anyone who reads it there can do everything the key can do, including spending the team's AI credits and editing or deleting anchors.
Which key to use
- In an app you publish: a client key, as
rvApiKey, withrvProjectIdset to the project that key belongs to. - On your backend: a secret key, for the operations a client key cannot call.
- In an internal demo with no backend: a build that only your team installs may hold a secret key. Create one with an expiry for it.
Configuring your key in an app
The key goes in rvApiKey and the project ID in rvProjectId. With Expo, set both in the @reactvision/react-viro plugin config. The plugin writes them to Info.plist as RVApiKey / RVProjectId and to AndroidManifest.xml as com.reactvision.RVApiKey / com.reactvision.RVProjectId. For bare React Native, add those entries yourself. See Use it in your app for each platform.
Calling the API directly
Every operation is under the base URL https://platform.reactvision.xyz/functions/v1, and every request sends the key in the x-api-key header:
x-api-key: rv_client_0123456789abcdef...
From a backend, use a secret key. See Calling the API from your backend.
Wrong key type
A key of the wrong type for an operation is refused with 403 API_KEY_TYPE_NOT_ALLOWED. In ViroReact, the method fails with "This endpoint does not accept this type of API key".
This usually means your app holds a client key and the method needs a secret key. Listing, editing and deleting anchors, attaching content to them and uploading images, videos and 3D models are secret-key operations, because anyone who has your app holds its client key. Make those calls from your backend with a secret key, or test them from an internal build that holds one. Client Keys and Secret Keys list which key each method accepts.
Project binding
A client key is bound to one project. A secret key is bound to one project if you choose one when you create it, and otherwise reaches every project of its team.
A bound key can only act on its own project. An anchor, scene, file or task of any other project is answered exactly as if it did not exist.
Deleting a project also deletes the keys bound to it, and apps that use them stop working.
Creating, replacing and deleting keys
Create and delete keys in Studio, on the team's API Keys page (in the sidebar, under Integrations). A team can hold any number of keys of either type.
To replace a key:
- Create the new key
- Move your apps and servers to it
- Delete the old key
If a secret key leaks, delete it in Studio and create a new one. Deleting a secret key also revokes every user token minted with it.
User tokens
A user token (rv_ut_) is minted by your backend with a secret key, through POST /app-user-tokens, for one signed-in app user. Your backend hands it to that user's app.
- A token lasts up to one hour.
- It reaches one project and one app user.
- Only the VPS operations will accept it, once VPS launches. Nothing else accepts a user token yet.
- Deleting the secret key that minted a token revokes the token.
Legacy keys
Keys created before client and secret keys existed (before Studio 1.5.0) are legacy keys. They are listed under Legacy keys in Studio, start with rv_live_, reach every project of their team, and keep working.
A legacy key can call every operation a secret key can, except:
- AI generation (
ai-imagesandai-models). A few legacy keys that ReactVision has listed keep it for a transitional period. - Listing, fetching and deleting app users' files (
GET /assets/list,GET /assets/{asset_id},DELETE /assets/{asset_id}). - Minting user tokens (
POST /app-user-tokens).
A legacy key gets the same responses as a secret key: no fields left out, private anchors included, and the general search bounds rather than the client-key ones.
Conversion
ReactVision is converting legacy keys. Each key's owner is emailed before anything changes, with the date that applies to that key.
- A key that an app uses on one project becomes a client key of that project. It keeps its string, so the app needs no rebuild.
- Until the key's grace date, it is still served as a legacy key. Every response to it carries two headers:
Deprecation: true
Sunset: <the grace date, as an HTTP date>
- From the grace date, the key is a client key. Studio's API Keys page shows each key's type and date.
Using a legacy key from a backend?
If the key is used from a backend for operations a client key cannot call, create a secret key before the date and use that instead.
To move an app to a new client key yourself instead, create one for the app's project and ship it. Then delete the legacy key once its Last used date stops changing.
Next Steps
- Client Keys: create the key that goes inside your app
- Secret Keys: the backend key for managing anchors, uploading files and calling the API
- Getting Started with ReactVision Spatial: create a project and get its project ID
Updated about 1 hour ago