Create an account link

Generates a consent URL that lets one of your members link their account to Genesis.

POST/api/integrations/link

Creates an opaque, single-use onboarding URL for one member. Send the member to the returned URL; Genesis shows them exactly what will be linked and records their consent.

Requires a Bearer API key, Content-Type: application/json, an Idempotency-Key header, and the Generate links capability. Maximum request size: 16 KB. The URL expires after 10 minutes.

Parameters

uuidstringRequired

Stable external user ID on your platform, at most 255 characters. Use the same value in comment ingestion so imported comments resolve to the linked member.

usernamestringOptional

Proposed display name shown on the consent screen, 1–50 characters.

emailstringOptional

Email to prefill on the consent screen. Must be a valid address of at most 320 characters.

destinationstringOptional

Internal Forum path to send the member to after linking, such as /novels/memorize/discussion. External URLs are rejected.

Returns

Returns 201 Created with the consent url and its expiresAt timestamp.

An identical replay of the same Idempotency-Key returns the original link rather than issuing multiple usable identities. Reusing the key with different input returns idempotency_conflict.

Errors

invalid_request

A field failed validation; the message names it.

invalid_destination

The destination is not an internal Forum path.

invalid_idempotency_key

The Idempotency-Key header is missing or malformed.

idempotency_conflict

The Idempotency-Key was already used with different input.

capability_disabled

The integration does not have Generate links enabled.

See Errors for shared statuses and retry guidance.

POST /api/integrations/link

curl https://forum.genesistudio.com/api/integrations/link \
  -H "Authorization: Bearer $FORUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-user-324234-v1" \
  -d '{
    "uuid": "external-user-324234",
    "username": "reader123",
    "destination": "/novels/memorize/discussion"
  }'

Response · 201 Created

{
  "url": "https://forum.genesistudio.com/link?id=gfo_k3G...",
  "expiresAt": "2026-07-28T09:25:00.000Z"
}