API Reference

xAI Identity API

Identity, SSO & authentication for the whole ecosystem

xAI Identity is a central multi-realm CIAM service. Every product shares one sign-in session (SSO) via the `xv_session` cookie on the `.xai.io.vn` domain. Integrating apps authenticate users through the introspection endpoint, or redirect to the central sign-in page.

Base URL

https://identity.xai.io.vn

Authentication

Lucia-style sessions: the token lives in the `xv_session` cookie (HttpOnly, Domain=.xai.io.vn). To authenticate a user from your app, call `GET /api/session` with the cookie — the browser sends it automatically to every subdomain.

Authentication

GET /api/session

Introspect the current session (CORS for *.xai.io.vn)

Auth: Cookie `xv_session` (auto-sent)

Example request

curl 'https://identity.xai.io.vn/api/session' \
  -H 'Cookie: xv_session=<token>' \
  -H 'Origin: https://your-app.xai.io.vn'

const res = await fetch('https://identity.xai.io.vn/api/session', {
  credentials: 'include', // gửi cookie xv_session
});
const session = await res.json();
if (session.authenticated) {
  console.log(session.user.email, session.memberships);
}

Example response

{
  "authenticated": true,
  "user": {
    "id": "usr_8f2c…",
    "email": "dev@partner.vn",
    "name": "Nguyễn An",
    "realmId": "xvalley"
  },
  "memberships": [
    { "org_id": "org_12ab", "org_name": "Đối tác ABC", "role": "admin" }
  ],
  "expiresAt": 1769990400
}

POST /api/auth/login

Auth: None (public)

Body parameters

Field	Type	Description
`email`*	`string`	User email
`password`*	`string`	Password

Example request

curl -X POST 'https://identity.xai.io.vn/api/auth/login' \
  -H 'Origin: https://identity.xai.io.vn' \
  -F 'email=dev@partner.vn' \
  -F 'password=••••••••'

Example response

{ "ok": true, "redirect": "/account" }

Error codes

`400 missing_credentials`	Missing email or password
`401 invalid_credentials`	Wrong credentials

POST /api/auth/register

Trial sign-up — creates a tenant + admin user

Auth: None (public)

Body parameters

Field	Type	Description
`email`*	`string`	Admin email
`password`*	`string`	Password
`name`*	`string`	User name
`org`	`string`	Organization (tenant) name

Example response

{ "ok": true, "redirect": "/account", "orgId": "org_12ab" }

Error codes

400 missing_fields Missing required field

POST /api/auth/logout

Sign out — invalidate session & clear cookie

Auth: Cookie `xv_session`

Example response

{ "ok": true }

Decentralized Identity (DID / VC)

POST /api/did/issue

Issue a Verifiable Credential (SD-JWT) to a user

Auth: Cookie `xv_session` (signed in)

Body parameters

Field	Type	Description
`type`*	`string`	`Identity` or `Membership`
`org_id`	`string`	Organization (for Membership credential)

Example response

{
  "ok": true,
  "credentialId": "vc_7d21…",
  "vct": "https://identity.xai.io.vn/vc/Identity",
  "sd_jwt": "eyJhbGciOiJFUzI1Ni␣…~WyJ…"
}

POST /api/did/verify

Verify an SD-JWT VC signature

Auth: None (public)

Body parameters

Field	Type	Description
`sd_jwt`*	`string`	The SD-JWT string to verify (or `credential`)

Example request

curl -X POST 'https://identity.xai.io.vn/api/did/verify' \
  -H 'Content-Type: application/json' \
  -d '{ "sd_jwt": "eyJhbGciOiJF…" }'

Example response

{
  "valid": true,
  "issuer": "did:web:identity.xai.io.vn",
  "type": "Identity",
  "claims": { "name": "Nguyễn An", "email": "dev@partner.vn" },
  "status": "active"
}

Error codes

400 missing_credential Missing `sd_jwt`/`credential`