Signup API
Signup API
XSI has built-in self-service signup by email. Signup is completed through an activation link: the user submits an email address, opens the link in the email to confirm, and the account is created. The API key is shown on the confirmation page and also sent in a welcome email.
- Master switch: the
SIGN_ENABLEenvironment variable (defaulttrue). When off, all/x-signrequests return403 {"success": false, "message": "Self-registration is currently disabled"}. - Email service dependency: activation emails are handed to a separate mail service through a Redis queue for delivery, so configure email before opening signup.
- Where new accounts belong depends on the deployment mode; see Account ownership.
Flow
POST /x-sign βββΆ Activation email (link valid for 10 minutes)
β
βΌ
GET /x-sign/activate?token=... βββΆ Confirmation page
β (user clicks Confirm)
βΌ
POST /x-sign/activate βββΆ Account created; page shows the API key and a welcome email is sentOpening the link (GET) only shows the confirmation page and does not create the account, so that email security scanners prefetching the link cannot trigger an accidental activation.
Send an activation email
curl -X POST "$XSI_BASE_URL/x-sign" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "referral_code": "pk-Xvs..."}'| Field | Required | Description |
|---|---|---|
email | Yes | Email address; converted to lowercase automatically |
referral_code | No | The referrer's public identifier (pk-Xvs...; see public_key in GET /dashboard/status). Ignored when XAI_REFERRAL_REWARD_RATE is 0 |
Successful response:
{"success": true, "message": "Verification code sent successfully", "data": {"email": "[email protected]"}}All responses have the {"success", "message", "data"} structure. Business errors return 400 with the reason in message:
message | Cause |
|---|---|
Invalid email address | Invalid email format |
Email domain is not allowed for self-registration | The signup domain policy is not satisfied |
Email already registered | The email is already registered |
invalid referral code | The referral code does not exist or the referrer is disabled |
Please wait before requesting another verification code | Repeated request for the same email within 2 minutes |
Too many verification codes requested from this IP today | More than 10 requests from the same IP today |
Failed to send verification email | The email could not be queued |
Activation
The link in the activation email is https://<XAI_API>/x-sign/activate?token=<48-character token>.
GET /x-sign/activate?token=...: returns the HTML confirmation page.POST /x-sign/activate(form fieldtoken): creates the account and returns an HTML success page that shows the new account's API key and a button to open the console (pointing toXAI_ADMINfor multi-tenant deployments andXAI_MANAGEfor single-tenant deployments).- An invalid or expired token shows
Invalid or expired activation link.
The created account:
| Attribute | Value |
|---|---|
| Account name | Random system name (u_ prefix for single-tenant, o_ prefix for multi-tenant) |
| Display name | Generated from the email's local part |
| API key | A newly generated 51-character sk-Xvs key, plus a public identifier pk-Xvs... |
| Signup bonus | XAI_CREDIT (code default: 2 for single-tenant, 120 for multi-tenant; 0 in the deployment template), valid for 1 month |
| Sub-account quota | 1 |
Account ownership
| Deployment mode | New account |
|---|---|
Single-tenant (SINGLE_TENANT=true, default) | Becomes a regular account under the root tenant, inheriting root's Level, Gear, Role, prices and rate limits |
Multi-tenant (SINGLE_TENANT=false) | Becomes a new tenant owner with its own key pool, configuration and prices; after signing in to the configuration console, the owner adds their own upstream keys |
Signup domain policy
Set by root through SIGNUP_ALLOW_DOMAINS and SIGNUP_DENY_DOMAINS in /x-config, and applied to all signups. For the syntax, see Tenant Configuration API.
Abuse protection
These limits apply when SAFE_ENABLE (default true) is on. Except for distinct emails, which are checked only in POST /x-sign (returning 400 when exceeded), the limits are shared by POST /x-sign and POST /x-sign/activate:
| Limit | Default |
|---|---|
| Requests per minute / hour / day | 3 / 10 / 20 |
| Distinct emails per IP per day | 5 |
| Site-wide signup requests per day | 10000 |
| Progressive delay | The more requests within the same hour, the longer the server waits (up to 15 seconds) |
| Automatic ban | Banned for 3 hours once suspicious behavior reaches the threshold |
Requests rejected by the rate limits or the site-wide quota return 429 with the body {"success": false, "message": "..."}. Per-IP limits do not apply when the detected client IP is still a trusted proxy address. Client IP detection relies on TRUSTED_PROXY_CIDRS; make sure your reverse proxy passes the real client IP correctly. See Reverse Proxy.