Doc Summary
Linking attaches an additional identity — an OAuth2 provider, an OIDC provider, or an email/username and password — to a User that already has an active Session. It’s a separate, explicit action from logging in, and it’s the only way to combine two identities into one account.
Note
Logging in via OIDC or OAuth2 never merges into a Session you already have. Login resolves purely from the token’s claims — if the provider identity has been seen before, it signs into that User; if not, it creates a brand-new User. So if you create an anonymous Session via Signup and then log in with, say, Twitch, you get a second, unrelated account, not your original anonymous account with Twitch attached. To attach Twitch to the anonymous account instead, call the linking endpoints below while the anonymous Session is still active, rather than logging in with Twitch directly.
Precondition: an active User Session #
Every linking endpoint requires the caller to already hold a Session at the User or SUPERUSER level (an anonymous/UNPRIVILEGED Session doesn’t qualify). Calling any of them without one returns a 403 Forbidden — “Authentication required to link accounts” for OAuth2/OIDC, “Authentication required to link credentials” for email/username-password. The identity is always attached to the User making the request; there’s no way to link on behalf of another User.
Endpoints #
POST /User/me/link/OAuth2 #
Links an OAuth2 identity, validated the same way an OAuth2 login is. Request body:
{
"schemeId": "<OAuth2 auth scheme id>",
"requestParameters": { "...": "..." },
"profileId": "<optional>",
"profileSelector": "<optional>"
}If the external id is already linked to a different User, the request fails. If it’s already linked to the calling User, the call is Idempotent — no duplicate link is created. On success it returns a full Session, the same as a login call.
POST /User/me/link/OIDC #
Links an OIDC identity from a JWT. Request body:
{
"JWT": "<id_token>",
"profileId": "<optional>",
"profileSelector": "<optional>"
}If the token’s sub is already linked to a different User, the request fails. If the token’s email claim is already linked to a different User, that’s handled more leniently: the sub still links successfully, and the email simply isn’t attached (no error). Linking this way does capture the provider’s returned Profile claims into User.linkedAccountProfiles, the same audit trail described in Users and Profiles — but unlike a fresh anonymous login, it does not fill in the flat displayName/firstName/lastName fields.
POST /User/me/link/email-password #
{
"email": "User@example.com",
"password": "..."
}The email must already exist as a verified email UID on the calling User — see Email Verification for how to verify one first. If the email belongs to a different account, the request is rejected. On success it sets the password and returns the updated User.
POST /User/me/link/username-password #
{
"username": "...",
"password": "..."
}If the calling User already has a different name set, this is rejected — name changes have to go through an explicit update, not linking. If the requested username is already taken by another User, it’s rejected as well. Otherwise it claims the username and sets the password, returning the updated User.
What happens on a conflict #
In every case, an identity already linked to another User is rejected rather than silently reassigned or merged — Elements never combines two existing accounts into one by linking. If you need one physical player to end up with a single account after using two different identities independently, that has to be handled as a deliberate migration, not a linking call.
An identity already linked to the same User that’s making the request is treated as a no-op success rather than an error, so clients don’t need to check “is this already linked?” before calling these endpoints.