Skip to content

Trial Claim#

These are the public, unauthenticated endpoints that end-users hit through a referral link to claim a trial. No account or token is required.

Validate a referral code#

GET /partner/referral/{code}/validate — public

Checks whether a referral code is usable (active, not expired, not over its usage limit). Use this to show the user whether their link is valid before they fill out the signup form.

curl https://api.terraquant.tech/api/partner/referral/Hk3xQz7Lm2pR9sTv/validate

Response — ReferralValidateResponse#

Field Type Notes
valid bool Whether the code can currently be used.
trial_duration_days int Trial length the code grants; 0 when valid is false. 
{ "valid": true, "trial_duration_days": 30 }

This endpoint always returns 200 — an unusable code yields { "valid": false, "trial_duration_days": 0 } rather than an error.

Claim a trial#

POST /partner/trial/claim — public, rate-limited

Creates a new user account and issues a time-limited trial license in one step, then returns auth tokens and the license key.

Rate limit

This endpoint is limited to 5 requests per hour per IP address. Exceeding it returns 429 Too Many Requests.

Request body (TrialClaimRequest)#

Field Type Required Constraints
code string Yes 1–32 chars; a valid referral code
username string Yes 3–64 chars; must be unique
email string (email) Yes max 170 chars; must be unique and not previously used for a trial
password string Yes min 8 chars
firstName string Yes max 128 chars
lastName string Yes max 128 chars
organization string Yes max 170 chars 
curl -X POST https://api.terraquant.tech/api/partner/trial/claim \
  -H "Content-Type: application/json" \
  -d '{
    "code": "Hk3xQz7Lm2pR9sTv",
    "username": "jdoe",
    "email": "jdoe@example.com",
    "password": "s3curePassw0rd",
    "firstName": "Jane",
    "lastName": "Doe",
    "organization": "Acme Labs"
  }'

POST /api/partner/trial/claim HTTP/1.1
Host: api.terraquant.tech
Content-Type: application/json

{
  "code": "Hk3xQz7Lm2pR9sTv",
  "username": "jdoe",
  "email": "jdoe@example.com",
  "password": "s3curePassw0rd",
  "firstName": "Jane",
  "lastName": "Doe",
  "organization": "Acme Labs"
}

Response — TrialClaimResponse#

Field Type Notes
access_token string JWT access token for the new user.
refresh_token string JWT refresh token.
user object The created user (id, username, email, organization, name, privileges, …).
license_key string Base64-encoded combined license key for activating NucleI. 
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "user": {
    "id": "c7d8...f2",
    "username": "jdoe",
    "email": "jdoe@example.com",
    "organization": "Acme Labs",
    "firstName": "Jane",
    "lastName": "Doe",
    "privileges": "basic",
    "email_verified": true,
    "is_active": true,
    "created_at": "2026-06-16T10:10:00Z",
    "last_login": null
  },
  "license_key": "Base64EncodedLicenseKey=="
}

The trial length comes from the referral link (trial_duration_days, default 28). On success the link's uses_count is incremented. See Errors for the 409/410 conditions (duplicate username/email, expired or exhausted link).