API Reference

xAI Identity API

Định danh, SSO & xác thực số cho toàn hệ sinh thái

xAI Identity là dịch vụ CIAM đa realm trung tâm. Mọi sản phẩm trong hệ sinh thái dùng chung một phiên đăng nhập (SSO) qua cookie `xv_session` trên miền `.xai.io.vn`. App tích hợp xác thực người dùng bằng endpoint introspection, hoặc redirect tới trang đăng nhập trung tâm.

Base URL

https://identity.xai.io.vn

Xác thực

Phiên kiểu Lucia: token lưu trong cookie `xv_session` (HttpOnly, Domain=.xai.io.vn). Để xác thực người dùng từ app của bạn, gọi `GET /api/session` kèm cookie — trình duyệt tự gửi cookie cho mọi subdomain.

Xác thực

GET /api/session

Introspection phiên hiện tại (CORS cho *.xai.io.vn)

Xác thực: Cookie `xv_session` (tự gửi)

Ví dụ yêu cầu

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);
}

Phản hồi mẫu

{
  "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

Đăng nhập bằng email + mật khẩu (form)

Xác thực: Không (công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`email`*	`string`	Email người dùng
`password`*	`string`	Mật khẩu

Ví dụ yêu cầu

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=••••••••'

Phản hồi mẫu

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

Mã lỗi

`400 missing_credentials`	Thiếu email hoặc mật khẩu
`401 invalid_credentials`	Sai thông tin đăng nhập

POST /api/auth/register

Đăng ký dùng thử — tạo tenant + người dùng admin

Xác thực: Không (công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`email`*	`string`	Email admin
`password`*	`string`	Mật khẩu
`name`*	`string`	Tên người dùng
`org`	`string`	Tên tổ chức (tenant)

Phản hồi mẫu

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

Mã lỗi

400 missing_fields Thiếu trường bắt buộc

POST /api/auth/logout

Đăng xuất — vô hiệu hóa phiên & xóa cookie

Xác thực: Cookie `xv_session`

Phản hồi mẫu

{ "ok": true }

Định danh phi tập trung (DID / VC)

POST /api/did/issue

Cấp Verifiable Credential (SD-JWT) cho người dùng

Xác thực: Cookie `xv_session` (đã đăng nhập)

Tham số (body)

Trường	Kiểu	Mô tả
`type`*	`string`	`Identity` hoặc `Membership`
`org_id`	`string`	Tổ chức (cho credential Membership)

Phản hồi mẫu

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

POST /api/did/verify

Xác minh chữ ký SD-JWT VC

Xác thực: Không (công khai)

Tham số (body)

Trường	Kiểu	Mô tả
`sd_jwt`*	`string`	Chuỗi SD-JWT cần xác minh (hoặc `credential`)

Ví dụ yêu cầu

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

Phản hồi mẫu

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

Mã lỗi

400 missing_credential Thiếu `sd_jwt`/`credential`