POST /api/link/start

Last updated 2 September 2026.

POST/api/link/start
Reserve a link request for one of your users. Returns the URL to send them to. The request is valid for ten minutes; the ticket that comes back after they confirm is valid for two.

Request

FieldTypeRules
subjectstringrequiredYour id for the user. See the subject rules.
returnUrlstringrequiredAbsolute http(s) URL on a registered origin. No credentials, no fragment, no `ticket` query parameter. Everything else in its query string is preserved verbatim.
subjectLabelstring | nulloptionalShown to the player on the confirm screen. ≤100 characters after whitespace collapse.
POST /api/link/start
Authorization: Bearer sk_yourservice_…
Content-Type: application/json

{
  "subject": "u_8f31c2",
  "returnUrl": "https://your.origin/link/trivela/callback?n=3f9a1c",
  "subjectLabel": "ThePretorians"
}

Responses

200Reserved. Redirect the player to url.
{
  "requestId": "9b1d…e4f2",                                   // 64 hex
  "url": "https://www.trivela.team/link/9b1d…e4f2",
  "expiresAt": "2026-09-02T09:12:41.000Z"                     // 10 minutes from now
}
400A field failed validation. One of:
{ "error": "subject …" }                                        // any subject rule
{ "error": "subjectLabel …" }                                   // any label rule
{ "error": "returnUrl must be a string." }
{ "error": "returnUrl must be an absolute URL." }
{ "error": "returnUrl must be http or https." }
{ "error": "returnUrl must not contain credentials." }
{ "error": "returnUrl must not contain a fragment." }
{ "error": "returnUrl must not already carry a ticket parameter." }
{ "error": "returnUrl origin https://x.example is not registered." }
401Bad or missing key.
{ "error": "Unknown or missing service key." }

What happens next

The player confirms at url. On confirm, Trivela redirects them to your returnUrl with ticket=<64 hex> appended, and your callback calls /api/link/redeem. If the request expires or the player declines, nothing is sent to you.