Skip to content

Referral Links & API Keys#

These endpoints let partners manage their referral links and API keys. Unless noted otherwise, they require a JWT Bearer token for a partner or admin account.

Object shapes#

ReferralLinkResponse#

Field Type Notes
id UUID Link identifier.
created_by UUID Owning partner's user id.
code string URL-safe referral code.
url string Full trial URL: https://terraquant.tech/trial/{code}.
label string | null Optional human-friendly name.
uses_count int How many trials have been claimed via this link.
max_uses int | null Usage cap, if set.
expires_at datetime | null Expiry, if set.
is_active bool false once deactivated.
trial_duration_days int Length of trials issued by this link.
created_at datetime Creation time.

PartnerAPIKeyResponse#

Field Type Notes
id UUID Key identifier.
owner_id UUID Owning partner's user id.
name string Label given at creation.
token string | null Raw key — only present in the create response.
last_used datetime | null Updated on each API-key request.
is_active bool Whether the key is usable.
created_at datetime Creation time.

POST /partner/referral-links — JWT auth

Request body (ReferralLinkCreate)#

Field Type Required Constraints Default
label string | null No max 255 chars null
max_uses int | null No 1–10000 null (unlimited)
expires_at datetime | null No ISO 8601 null (never)
trial_duration_days int No 1–90 28 
curl -X POST https://api.terraquant.tech/api/partner/referral-links \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Spring campaign",
    "max_uses": 500,
    "trial_duration_days": 30
  }'

POST /api/partner/referral-links HTTP/1.1
Host: api.terraquant.tech
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "label": "Spring campaign",
  "max_uses": 500,
  "trial_duration_days": 30
}

Response — ReferralLinkResponse#

{
  "id": "f4c1...e9",
  "created_by": "a1b2...c3",
  "code": "Hk3xQz7Lm2pR9sTv",
  "url": "https://terraquant.tech/trial/Hk3xQz7Lm2pR9sTv",
  "label": "Spring campaign",
  "uses_count": 0,
  "max_uses": 500,
  "expires_at": null,
  "is_active": true,
  "trial_duration_days": 30,
  "created_at": "2026-06-16T10:00:00Z"
}

GET /partner/referral-links — JWT auth

Returns the caller's links (newest first) as a JSON array of ReferralLinkResponse.

curl https://api.terraquant.tech/api/partner/referral-links \
  -H "Authorization: Bearer <jwt_token>"

DELETE /partner/referral-links/{link_id} — JWT auth

Sets is_active to false; the link can no longer be used to claim trials.

curl -X DELETE https://api.terraquant.tech/api/partner/referral-links/f4c1...e9 \
  -H "Authorization: Bearer <jwt_token>"

{ "status": "deactivated" }

Returns 404 if the link does not exist or is not owned by the caller.

POST /partner/api/referral-links — API-key auth

Identical body and response to POST /partner/referral-links, but authenticated with the X-API-Key header instead of a JWT. Use this for server-to-server automation.

curl -X POST https://api.terraquant.tech/api/partner/api/referral-links \
  -H "X-API-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Automated", "trial_duration_days": 14 }'

POST /api/partner/api/referral-links HTTP/1.1
Host: api.terraquant.tech
X-API-Key: <token>
Content-Type: application/json

{ "label": "Automated", "trial_duration_days": 14 }

Create an API key#

POST /partner/api-keys — JWT auth

Request body (PartnerAPIKeyCreate)#

Field Type Required Constraints
name string Yes 1–128 chars 
curl -X POST https://api.terraquant.tech/api/partner/api-keys \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI integration" }'

Response — PartnerAPIKeyResponse#

{
  "id": "9a8b...d1",
  "owner_id": "a1b2...c3",
  "name": "CI integration",
  "token": "K9d-3fJq...raw_token_shown_once",
  "last_used": null,
  "is_active": true,
  "created_at": "2026-06-16T10:05:00Z"
}

Warning

Save token now — it is never returned again. See Authentication.

List API keys#

GET /partner/api-keys — JWT auth

Returns the caller's keys (newest first). The token field is always null here.

curl https://api.terraquant.tech/api/partner/api-keys \
  -H "Authorization: Bearer <jwt_token>"

Revoke an API key#

DELETE /partner/api-keys/{key_id} — JWT auth

Permanently deletes the key.

curl -X DELETE https://api.terraquant.tech/api/partner/api-keys/9a8b...d1 \
  -H "Authorization: Bearer <jwt_token>"

{ "status": "revoked" }

Returns 404 if the key does not exist or is not owned by the caller.