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_ENABLE environment variable (default true). When off, all /x-sign requests return 403 {"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 sent

Opening 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..."}'
FieldRequiredDescription
emailYesEmail address; converted to lowercase automatically
referral_codeNoThe 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:

messageCause
Invalid email addressInvalid email format
Email domain is not allowed for self-registrationThe signup domain policy is not satisfied
Email already registeredThe email is already registered
invalid referral codeThe referral code does not exist or the referrer is disabled
Please wait before requesting another verification codeRepeated request for the same email within 2 minutes
Too many verification codes requested from this IP todayMore than 10 requests from the same IP today
Failed to send verification emailThe 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 field token): 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 to XAI_ADMIN for multi-tenant deployments and XAI_MANAGE for single-tenant deployments).
  • An invalid or expired token shows Invalid or expired activation link.

The created account:

AttributeValue
Account nameRandom system name (u_ prefix for single-tenant, o_ prefix for multi-tenant)
Display nameGenerated from the email's local part
API keyA newly generated 51-character sk-Xvs key, plus a public identifier pk-Xvs...
Signup bonusXAI_CREDIT (code default: 2 for single-tenant, 120 for multi-tenant; 0 in the deployment template), valid for 1 month
Sub-account quota1

Account ownership

Deployment modeNew 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:

LimitDefault
Requests per minute / hour / day3 / 10 / 20
Distinct emails per IP per day5
Site-wide signup requests per day10000
Progressive delayThe more requests within the same hour, the longer the server waits (up to 15 seconds)
Automatic banBanned 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.