Authentication
Client keys and secret keys: which ReactVision API key to use where, and how legacy keys move over.
The ReactVision API serves a ReactVision Editor team's cloud anchors, geospatial anchors, uploaded files, Editor scenes and projects, scene API requests, AI generation, co-location rooms and Advanced VPS locations and scans. 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 ReactVision Editor 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. The Editor 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 Editor scenes and projects, runs a scene's API requests, uses co-location rooms, and reads the project's shared Advanced VPS locations and downloads their maps. 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, mints user tokens, and makes and manages Advanced VPS locations and scans. 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.
Scopes
A secret key can be limited to some parts of the API when you create it (in the Editor, from Editor 1.6.0). A backend that only mints user tokens, for example, can hold a key with the vps scope alone, which cannot edit anchors or spend AI credits. A secret key created with full access reaches every scope, and so do client and legacy keys, which cannot be limited.
| Scope | Operations |
|---|---|
anchors | Cloud anchors and geospatial anchors |
scenes | Projects, scenes and scene API requests |
assets | Uploading, listing, fetching and deleting files |
ai | AI image and 3D model generation |
colocation | Co-location rooms, and joining them from a device |
vps | Advanced VPS, and minting user tokens |
- An operation outside the key's scopes is refused with 403
API_KEY_SCOPE_NOT_ALLOWED. Each operation in the API reference names its scope. - A key's scopes cannot be changed after it is created. Create a new key with the scopes you want, move to it, then delete the old one.
- A user token carries
colocation,vpsor both: each of them its secret key holds, or the ones the mint names, so minting needs one of them. An operation outside a token's scopes is refused with 403APP_USER_TOKEN_SCOPE_NOT_ALLOWED.
Creating, replacing and deleting keys
Create and delete keys in the Editor, 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 the Editor 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.
- The app sends it as
Authorization: Bearer <token>, with the project inx-project-id. - The co-location room operations and the Advanced VPS operations accept it. Every other operation refuses it with 401
AUTH_ERROR. - It carries the
colocationscope, thevpsscope or both. See Scopes. - An expired token is refused with 401
APP_USER_TOKEN_EXPIRED: get a new one from your backend. In ViroReact 3.1.0,createUserTokenCredentials()does that for you. See Acting for a signed-in user and Co-Location. - Deleting the secret key that minted a token revokes the token.
Legacy keys
Keys created before client and secret keys existed (before Editor 1.5.0) are legacy keys. They are listed under Legacy keys in the Editor, 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). - The Advanced VPS operations other than reading locations, downloading their files and
GET /vps/server. On those, a legacy key sees the project's shared locations only, as a client key does.
Outside Advanced VPS, 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. The Editor'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 7 days ago