API reference

Game servers use these endpoints during avatar negotiation. Every response sends Access-Control-Allow-Origin: *, so browser-based clients can call them directly.

GET/api/public/m/<id>.json

The canonical avatar URL: a signed Universal Manifest v0.3 document. Pointers carry the model file, metadata and verify endpoint; facets carry the avatar's display name, tags and ability scores.

{
  "@context": "https://universalmanifest.net/ns/v0.3",
  "@id": "urn:uuid:<avatar-id>",
  "@type": ["um:Manifest"],
  "manifestVersion": "0.3",
  "subject": "did:web:<host>:u:<handle>",
  "issuedAt": "…", "expiresAt": "…",
  "requiredTrustTier": 0,
  "pointers": [{ "@type": "um:assetPointer", "target": "https://…/api/public/f/<id>.vrm" }],
  "facets":   [{ "@type": "um:Facet", "name": "spatialAvatar", "entity": { … } }],
  "signature": {
    "algorithm": "Ed25519",
    "canonicalization": "JCS-RFC8785",
    "keyRef": "https://…/api/public/um-key#um-signing-1",
    "publicKeySpkiB64": "MCowBQYDK2VwAyEA…",
    "value": "<base64url>"
  }
}

GET/api/public/um-key

Ed25519 verification key material (SPKI + JWK) referenced by every manifest signature.keyRef.

POST/api/public/verify

Checks that the connecting identity is entitled to the offered avatar and returns its properties plus the delivery mode (relay or import).

{
  "identity": "roderick",
  "url": "https://…/api/public/m/<id>.json",
  "proof": { "scheme": "jws-detached", "value": "<compact JWS>" }
}

GET/api/public/avatars/<id>

Metadata only: name, tags, licence, ability scores, file size, content hash and download URL.

GET/api/public/f/<id>.<glb|vrm|gltf>

Streams the model file with the correct content type. Private avatars return 404.

GET/api/public/jwks

ES256 public keys used to verify jws-detached proofs.

GET/.well-known/teleport-avatars

Lists identities and the avatar URLs they may present — the crypto-free proof scheme.

Proof schemes

jws-detached — the owner mints a short-lived ES256 token from their library that binds their handle to a specific avatar URL. Servers verify it against the JWKS endpoint, no round trip to us required.

well-known-url — servers fetch /.well-known/teleport-avatars and check that the claimed identity lists the offered URL. Simpler, cacheable, no signature handling.