HomeGuidesAPI ReferenceChangelogDiscussions
Hire a ReactVision Expert 🛠️Launch Studio 🖥️Sponsor on GitHub ❤️Log In
API Reference

Mint a user token

Secret key only. Scope: colocation or vps.

Mints a user token for one signed-in user of your app. Call it from your backend, never from the app: it needs a secret key.

A user token reaches one project and one app user, and lasts at most one hour. It carries scopes: the ones scopes names, or without it every one of colocation and vps that the minting key holds, and a key may mint only scopes it holds. User tokens are accepted by the co-location room operations, the co-location relay and the Advanced VPS operations; every other operation refuses them. Treat the token as opaque.

Deleting or expiring the secret key that minted a token revokes the token too. There is no other way to revoke one.

Mint only for a user your backend has signed in. If you need more protection against automated clients, your endpoint can first check App Attest (iOS), Play Integrity (Android) or Meta's attestation (Quest).

Limits, always enforced: 1,200 tokens a minute per key, and 60 an hour per key and app user. A backend can cache a token per app user until shortly before expires_at.

Your backend

Mint a token for the signed-in user and return it to the app:

const r = await fetch("https://platform.reactvision.xyz/functions/v1/app-user-tokens", {
  method: "POST",
  headers: { "x-api-key": process.env.RV_SECRET_KEY!, "content-type": "application/json" },
  body: JSON.stringify({ project_id: PROJECT_ID, app_user_id: user.id }),
})
const minted = await r.json() // { token, expires_at, expires_in, scopes }: return it to the signed-in app user as it is

Your app (Viro)

Viro calls credentials before every VPS request, a frame a second in server mode, and when a device joins a co-location room, so let createUserTokenCredentials keep the token. It asks your backend again only when the token is close to expiring or was refused, and Viro then sends the refused request once more with the new token.

import { createUserTokenCredentials } from "@reactvision/react-viro"

const credentials = createUserTokenCredentials({
  projectId: PROJECT_ID,
  fetchToken: async () => {
    const r = await fetch("https://api.example.com/rv-token", { headers: { Authorization: `Bearer ${session}` } })
    return r.json() // what this operation answered
  },
})
<ViroVPS arSceneNavigator={nav} credentials={credentials} />

Make one per signed-in user, or call credentials.clear() at sign-out.

Not counted against the monthly API request quota.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
uuid
required

The project the token reaches. A bound key may only name its own.

string
required
length between 1 and 255

Your id for the signed-in app user: 1 to 255 printable ASCII characters, no spaces, not . or ...

integer
60 to 3600

Lifetime, 60 to 3600 seconds. Default 3600.

scopes
array of strings
length ≥ 1

The scopes the token carries, each one the key holds. Default: every token scope the key holds.

scopes
Allowed:
Responses

INVALID_BODY: the body is not a JSON object, project_id is not a UUID, ttl_seconds is not an integer from 60 to 3600, or scopes is empty or names something other than colocation and vps.

INVALID_APP_USER_ID: app_user_id is not 1 to 255 printable ASCII characters without spaces, or is . or ...

MISSING_API_KEY: no x-api-key header.

INVALID_API_KEY_FORMAT: the key is not rv_live_, rv_client_ or rv_secret_ followed by 64 lowercase hexadecimal characters.

INVALID_API_KEY: no such key, or a key sent with the wrong prefix for its type.

API_KEY_EXPIRED: the key is past its expiry date.

API_KEY_TYPE_NOT_ALLOWED: a client key or a legacy key. This operation needs a secret key.

API_KEY_SCOPE_NOT_ALLOWED: the key holds neither colocation nor vps, or scopes names one it does not hold.

PROJECT_NOT_FOUND: project_id does not exist, belongs to another team, or is not the project the key is bound to.

RATE_LIMITED: over 1,200 tokens a minute for the key, or 60 an hour for the key and app user. Wait the number of seconds in Retry-After.

INTERNAL_ERROR: an unexpected error. Retry, and quote meta.request_id to support if it persists.

API_KEY_LOOKUP_FAILED: the key could not be checked. Retry; this does not mean the key is invalid.

PROJECT_LOOKUP_FAILED: the project could not be checked. Retry.

APP_USER_TOKEN_SIGNING_UNAVAILABLE: tokens cannot be signed right now. Retry.

Language
Credentials
Header
LoadingLoading…
Response
Choose an example:
application/json