Account linking

End-to-end flow

1. Your server creates or requests a short-lived link.
2. Redirect the member to /link?id=....
3. Genesis validates the integration, token, expiry, and destination.
4. Genesis shows the source and proposed identity fields before any account change.
5. The member accepts or declines. Declining does not create or link an account.
6. On acceptance, the member signs in with password or OAuth, or creates and verifies a Genesis account.
7. Genesis links the external subject and redirects to the safe internal destination.

Creating a link

Most partners call POST /api/integrations/link from their backend and redirect the member to the returned URL. The link expires after 10 minutes and is consumed by the final decision; if it expires first, request a new link with a new idempotency key.

Use an HTTP redirect or a clear user action to open the exact returned URL. Do not parse, rewrite, or append data to the opaque id, and treat the complete URL as sensitive rather than logging it.

Partners that prefer not to send identity fields in an API request can generate signed links instead.

Identity fields

The uuid you send, or the JWT sub claim, must be a stable identifier for that person within your platform. Do not use a username or email, because both can change, and never recycle an identifier from a deleted account. Genesis scopes the value to your integration, so two partners can use the same UUID without collision.

username is optional but helps explain the link to the member. email, if supplied, must match the email of the Genesis account that completes linking. destination is the internal Forum path opened after the flow finishes, such as /novels/memorize/discussion; absolute URLs and cross-origin redirects are rejected.

If the member only has a username on your platform, Genesis collects their email during account creation. Never transmit or prefill a partner password.

Consent and completion

Genesis displays the partner name, the proposed fields, the purpose of the link, and the destination before showing Accept and Decline. Nothing is linked merely because the page was opened, and declines are audited.

Existing members sign in with their Genesis password or an OAuth provider such as Google or Discord. New members supply an email, choose a Genesis username, and set a new password or use OAuth; email verification uses a one-hour continuation so it can finish without extending the original token.

Linking applies to the external identity as a whole: historical imported comments from the same UUID resolve to the linked Genesis profile. An external identity already linked to a different Genesis account returns a conflict and requires support review; it is never silently reassigned.

Security

Account links are short-lived, single-use, integration-scoped, and consent-gated. Treat raw API keys, private signing keys, opaque link IDs, and unfinished onboarding URLs as secrets: redact them from logs and support screenshots, and avoid sending email or username fields Genesis can collect directly.

Never put a password in a link request or JSON claims; your password database and Genesis authentication stay separate.

If a credential is exposed, email info@genesistudio.com immediately to rotate it, and say explicitly if the integration should be disabled while you investigate. Include affected time windows and token IDs in the report, never raw credentials.