Developer documentation

Build on ALYSSIUN ID

Portable identity, avatars, profile cards, and trust for apps, games, simulations, digital twins, websites, and spatial systems. The website uses the exact same API documented here.

Continue with ALYSSIUN ID

“Continue with ALYSSIUN ID” lets people sign in to your app with their portable ALYSSIUN identity — bringing a verified handle, profile card, avatar, and trust standing with them. One private ALYSSIUN Account can own many public IDs, so a person chooses which public identity to present to your app.

During V1 the foundation (developer apps, scoped API keys, allowed domains, callback URLs) is live and powers read access to public identity data. The interactive end-user login button for third-party apps builds on this same client + scope model.

App data vs. customer data

A clean separation: you keep your own app and customer data. ALYSSIUN provides the identity layer — profile, avatar, card, verification, and trust — which you reference by handle. ALYSSIUN never asks for, stores, or exposes your customer records, and never exposes the private root ALYSSIUN Account behind a public ID.

Authentication & keys

Create a developer app at /developer and issue an API key. The full key is shown once (only a SHA-256 hash is stored). Send it as a bearer token:

Authorization: Bearer aid_live_xxxxxxxxxxxxxxxxxxxxxxxx

Public profile reads are open to anyone; if a key is sent it must carry the matching scope. Base URL: https://id.alyssiun.com

Scopes

Scope	Grants
profile:read	Public ID profile fields
avatar:read	Avatar profile (name, style, image/model, parametric config, render mode, purpose)
card:read	Full profile card (profile + avatar + trust)
trust:basic	Neutral trust standing (verified/trusted/limited/under review)

Request only what you need. Private safety history is never exposed by any scope.

Profile API

Anyone can create their own ALYSSIUN ID and design their own avatar; developers fetch any public user's identity by handle. In every example below, example_user is a placeholder — replace it with any public ALYSSIUN ID handle.

GET/api/v1/ids/:handle

curl https://id.alyssiun.com/api/v1/ids/example_user \
  -H "Authorization: Bearer aid_live_..."

{
  "id": {
    "handle": "example_user",
    "display_name": "Example User",
    "title": "Creator",
    "company": "Example Studio",
    "website": "https://example.com",
    "trust": { "standing": "verified", "label": "Verified" },
    "profile_url": "https://id.alyssiun.com/@example_user"
  }
}

Card API

The embeddable identity unit: profile + avatar + trust in one call.

GET/api/v1/cards/:handle

curl https://id.alyssiun.com/api/v1/cards/example_user \
  -H "Authorization: Bearer aid_live_..."   # scope: card:read

Avatar API

:id accepts a public ID's numeric id or its @handle.

GET/api/v1/avatars/:id

curl https://id.alyssiun.com/api/v1/avatars/example_user \
  -H "Authorization: Bearer aid_live_..."   # scope: avatar:read

{ "avatar": { "avatar_name": "Example — Avatar",
  "avatar_style": "professional",
  "image_url": null, "model_url": null, "model_type": null,
  "config": { "version": 1, "bodyShape": "regular", "skinTone": "#e8b18c",
    "hairStyle": "short", "hairColor": "#2a2320", "topColor": "#3b6fb0",
    "bottomColor": "#2b2f37", "shoeColor": "#1c1d22", "accentColor": "#2f7d62",
    "silhouette": "neutral" },
  "render_mode": "generated",
  "purpose": "business" },
  "handle": "example_user" }

How to render. Use render_mode to decide what to draw, in this precedence: custom_model (a custom .glb at model_url) → generated (draw the parametric avatar from config) → placeholder (neither; fall back to image/initials). config is a small, public-safe set of visual settings only (body/silhouette presets and skin/hair/clothing colours) — it never contains an account, user, or database id. Owners edit it in the live avatar designer at /dashboard → Avatar; saving writes only config and leaves name/style/model untouched.

POST/api/v1/avatars/:id/config · owner · body: { config }

3D model (advanced). Owners can upload a binary glTF .glb avatar model (owner session, max 25 MB). When present, model_url is a public, opaque media URL and model_type is "glb" — no account, user, or database id is ever encoded in it. USDZ/glTF-json are planned. This is the foundation for the forthcoming avatar creator; ALYSSIUN Engine should consume the public model_url/model_type fields only.

POST/api/v1/ids/:id/avatar-model · owner · body: model/gltf-binary

DELETE/api/v1/ids/:id/avatar-model · owner

Engine & app integration

For real-time renderers (ALYSSIUN Engine, games, simulations, spatial apps) there is a single render-ready endpoint. It is keyed by @handle and returns only public-safe fields — never an internal numeric id, user id, account id, or hidden email.

GET/api/v1/avatars/:handle/public · public · scope: avatar:read (if a key is sent)

Switch on render_mode: custom_model → load the GLB at model_url; generated → build the parametric avatar from config; placeholder → draw image_url or initials.

GET https://id.alyssiun.com/api/v1/avatars/example_user/public

{ "avatar": {
  "handle": "example_user",
  "display_name": "Example User",
  "render_mode": "generated",          // custom_model | generated | placeholder
  "model_url": null,                    // use when render_mode === "custom_model"
  "model_type": null,                  // "glb" for uploaded models
  "config": {                          // use when render_mode === "generated"
    "version": 1, "bodyShape": "regular", "skinTone": "#e8b18c",
    "hairStyle": "short", "hairColor": "#2a2320", "topColor": "#3b6fb0",
    "bottomColor": "#2b2f37", "shoeColor": "#1c1d22", "accentColor": "#2f7d62",
    "silhouette": "neutral" },
  "image_url": null,                   // optional placeholder image
  "initials": "EU",                    // placeholder fallback
  "avatar_name": "Example — Avatar",
  "avatar_style": "professional",
  "purpose": "business",
  "profile_url": "https://id.alyssiun.com/@example_user" } }

Frontend fetch. Works from any website — see the live avatar demo.

async function loadAvatar(handle) {
  const res = await fetch(`https://id.alyssiun.com/api/v1/avatars/${handle}/public`);
  if (!res.ok) throw new Error('avatar not found');
  const { avatar } = await res.json();
  return avatar; // render-ready, public-safe
}

Cross-origin (CORS). The public read endpoints — /avatars/:handle/public, /avatars/:id and /cards/:handle — return Access-Control-Allow-Origin: *, so any browser origin may GET them directly. They are credential-less by design: no cookie or session is sent or honoured cross-origin (no Allow-Credentials), and owner/session endpoints send no CORS headers, so they stay closed to other origins. Send an API key only from a trusted server — never embed one in public browser code.

Engine integration (pseudocode). The render switch is stable — new modes will only ever be added, so default to the placeholder.

avatar = AlyssiunID.fetchAvatar(handle)   // GET /avatars/:handle/public

switch avatar.render_mode:
  case "custom_model":
    model = Engine.loadGLB(avatar.model_url)        // avatar.model_type == "glb"
    Scene.spawn(model)
  case "generated":
    rig = Engine.buildParametricAvatar(avatar.config)  // colours + body/silhouette presets
    Scene.spawn(rig)
  default: // "placeholder"
    Scene.spawn(Engine.initialsCard(avatar.initials, avatar.image_url))

Unity, Unreal & native runtimes. The same public endpoint works from any HTTP client — Unity UnityWebRequest, Unreal’s HTTP module, or any game, simulation, or digital-twin runtime. Fetch the JSON, switch on render_mode, then load the .glb at model_url, build from config, or draw the initials. No key is required for public reads; the contract is identical across web, engine, and native.

Need the full identity (profile + trust + avatar) in one call instead? Use the Card API; its avatar object carries the same render_mode/model_url/config fields.

Trust Basic

Trust standing is a neutral operational label — verified · trusted · limited · under review. There is no public good/bad score and no private safety history. With trust:basic you can read the standing that is included in profile and card responses:

"trust": { "standing": "verified", "label": "Verified" }

SDKs

Official SDKs are planned to wrap these endpoints and the “Continue with ALYSSIUN ID” flow:

@alyssiun/avatar-js — available (source v0.1.0) · public avatar reads for web, apps, games & engines

@alyssiun/id-js — identity, profile, card, trust (planned)

Unity SDK — UnityWebRequest avatar/card loader + parametric builder (planned)

Unreal plugin — Blueprint / C++ avatar & card nodes (planned)

All SDKs are thin wrappers over the public REST contract above — nothing blocks shipping today by calling the API directly.

@alyssiun/avatar-js is the first SDK — a tiny, dependency-free, browser-safe wrapper over GET /avatars/:handle/public. No API key, no cookies. It uses the CORS-enabled public read endpoint, so it runs from any origin, and re-derives the render precedence (custom_model → generated → placeholder) locally. Source lives in the repo at packages/avatar-js; npm publish is pending.

// @alyssiun/avatar-js — public reads, no key, no cookies
import { fetchAvatar, resolveAvatarRenderMode } from '@alyssiun/avatar-js';

const avatar = await fetchAvatar('example_user');   // GET /avatars/:handle/public
switch (resolveAvatarRenderMode(avatar)) {            // custom_model | generated | placeholder
  case 'custom_model': loadGLB(avatar.model_url); break;     // model_type === 'glb'
  case 'generated':    buildParametric(avatar.config); break;
  default:             drawInitials(avatar.initials, avatar.image_url);
}

Try it on the live avatar demo, or call the REST API directly as shown above.

// preview of the planned @alyssiun/id-js API
import { AlyssiunID } from '@alyssiun/id-js';
const id = new AlyssiunID({ apiKey: process.env.ALYSSIUN_ID_KEY });
const card = await id.cards.get('example_user');