ReactVision Studio 1.5.0: Client and Secret API Keys
In Studio 1.5.0 we're making a major improvement to our platform's security by splitting API keys into two types, based on where the key lives:
- Client keys go inside your app. They are safe to expose because they can only do what an app needs, on one project.
- Secret keys stay on your backend. They can do everything, so they must never ship in an app.
Your existing keys will keep working, for now. Read on for what changes today, what is coming, and what (if anything) you need to do.
In short: what you need to do
- New app? Create a client key for the project it uses. Steps are at the end of this post.
- Using AI generation, or reading or deleting your app users' files? Those calls now need a secret key, sent from your backend.
- Does your app edit or delete anchors, or upload files, from the device? It still works today with your current key. Plan to move those calls to your backend with a secret key before your key is converted. We will contact you first.
- Anything else? Nothing to do today.
Client keys: for your app
A client key starts with rv_client_ and goes in ViroReact's rvApiKey. Treat it as public.
- One project only. You choose the project when you create the key. Set
rvProjectIdto the same project; the key refuses every other one. - Everything an app needs on a device: host and resolve cloud and geospatial anchors, fetch an anchor, find nearby anchors, load Studio scenes and projects, run a scene's API requests, and use co-location rooms.
- Slightly narrower results than a secret key: private cloud anchors are hidden, anchor reads leave out fields that identify other users, and a nearby search returns at most 50 anchors within 1,000 m.
- Always viewable. Studio can show a client key again at any time from the API Keys page.
Secret keys: for your backend
A secret key starts with rv_secret_ and stays on your own server.
- Team-wide or one project. It reaches every project in your team, or just one if you pick a project when you create it.
- Full access. It is the only key that can run AI image and 3D model generation and read or delete your app users' files. It can also list, edit and delete anchors, and upload images, videos and 3D models.
- Shown once. Studio shows it only when you create it, so store it somewhere safe.
- Never in a published app. The one exception is an internal demo with no backend, installed only by your team. In that case, set an expiry when you create the key (30 days to a year).
What each key can do
| Client key | Secret key | |
|---|---|---|
| Host and resolve cloud and geospatial anchors | Yes | Yes |
| Fetch an anchor, find nearby anchors | Yes | Yes |
| List, edit and delete anchors, attach and remove content | No | Yes |
Upload images, videos and 3D models (rvUploadAsset) | No | Yes |
Load Studio scenes and projects (StudioSceneNavigator) | Its own project | Yes |
| Run a scene's API requests | Yes | Yes |
| Co-location rooms | Yes | Yes |
| AI image and 3D model generation | No | Yes |
| Read and delete app users' files | No | Yes |
You can also create as many keys as you need, of either type. The old limit of five keys per team is gone.
Your existing keys
Every key created before today is now a legacy key. It keeps working, and apps that use it need no changes.
What changes today:
- AI generation (
ai-imagesandai-models) needs a secret key. - Listing, fetching and deleting app users' files needs a secret key.
- Requests for an anchor, scene, project or file that belongs to another team now get the same response as one that does not exist. The Errors page lists the codes.
What is coming next:
- Anchor searches will be capped at 100 results within 5,000 m.
- Rate limits will be introduced.
The changelog will announce the date before either is enforced.
Then, legacy keys will be converted to the new types. We will email each key's owner before anything changes, with the date for that key. A key that an app uses on a single project becomes a client key for that project and keeps the same key string, so you do not need to rebuild your app.
One case needs action before conversion. If your app edits or deletes anchors, or uploads files, directly from the device, it works today because legacy keys allow it. A client key will not, because everyone who installs your app has a copy of that key. Move those calls to your backend and make them with a secret key. We will contact the owners of keys that make these calls before anything changes.
A public API reference
The ReactVision API now has a public reference at viro-community.readme.io/reference. It covers every operation a key can call: cloud anchors, geospatial anchors, files, scenes, projects, scene API requests, AI images and models, and co-location rooms. Each operation lists the key types it accepts, its parameters, its responses and its error codes.
Good places to start:
- Authentication: which key goes where.
- Errors: every error code.
- Limits: quotas, search bounds and rate limits.
There is deliberately no "Try It" button. There is no test mode, so a secret key pasted into the page would act on your live data.
How to create a client key
- Open your team in ReactVision Studio and click API Keys, under Integrations in the sidebar.
- Click Create Key, give it a name, and choose Client key.
- Choose the project your app uses.
- Click Create and copy the key. Paste it into
rvApiKey, and setrvProjectIdto the same project.
For a key that ships in a published app, leave the expiration set to "No expiration". Otherwise the app stops working on that date.
What's next: user tokens
Secret keys can also create user tokens: short-lived credentials (up to an hour) for one signed-in user of your app. Your backend creates the token and hands it to that user's device. Nothing accepts user tokens yet. Advanced VPS will be the first feature that does, and we will write about it when it ships.
If anything does not work the way this post describes, tell us on Discord.