# Link a nexus

`POST https://api.nexus.gg/v1/manage/members/link`

Attaches an existing Nexus account to your creator group under your own `playerId`, using a short-lived `authCode` from `generateAuthCode`. This does not create a new member: `addMember` is hardcoded `false`, so the Nexus behind the `authCode` must already have some presence in your group, either a managed membership (a code you generated earlier for that `playerId` via `generateMember`, still unclaimed) or an existing group membership for that Nexus. If neither exists, the call fails with `400` and `code: InvalidAuthCode`, the same code returned when the auth code itself doesn't exist. A code that has expired (more than 30 minutes after `generateAuthCode` issued it) fails with `400` and `code: ExpiredAuthCode` instead. If the `playerId` you pass is already linked to a different member, the call fails with `400` and `code: PlayerAlreadyLinked`. If the Nexus behind the `authCode` is already linked to a different `playerId`, whether through a managed membership or an existing group membership, the call fails with `400` and `code: MemberAlreadyLinked`. On success the auth code is deleted immediately, so it can only be redeemed once. This method authenticates with a **secret** (`nexus_sk_...`) key.

## Authorizations

- `X-SHARED-SECRET` (string, header, required) - Send your **secret** API key (`nexus_sk_...`) in the `X-SHARED-SECRET` header. [Generate one](/authentication/api-keys/) in the Publisher Dashboard.

## Query parameters

- `groupId` (string) - Creator group to use for this operation. If your key is scoped to a single program, that group is always used regardless of this value; otherwise falls back to your default group when omitted.

## Request body (`application/x-www-form-urlencoded`)

- `playerId` (string, required) - Your identifier for the player to associate with the linked Nexus account.
- `authCode` (string, required) - The auth code the creator gave you, from `generateAuthCode`. Expires 30 minutes after issuance and can only be redeemed once.
- `playerMetadata` (object) - Additional player information to be applied to this member (such as their in game display name)

## Responses

### 200

Referral code of linked Nexus

#### Body (`application/json`)

- `groupId` (string) - ID of the creator group
- `groupName` (string) - Name of the creator group
- `id` (string) - The linked member's Nexus id.
- `playerId` (string) - Unique identifier for user that was linked to the Nexus represented by the specified authCode
- `codes` (array of object)

### 400

Bad request

#### Body (`application/json`)

- `code` (string) - CodeNotInGroup: Creator group is private, and specified code is not linked to it<br /> InvalidGroup: No creator group was found with the specified groupId<br/> InvalidAuthCode: AuthCode provided is not valid or the nexus it represents is not a member of your program<br/> ExpiredAuthCode: AuchCode provided has expired<br/> NexusNotFound: No Nexus was found to match the provided code<br/> PlayerNotInGroup: No group member found for the given playerId<br/> PlayerAlreadyLinked: The playerId provided has already been linked with a group member<br/> MemberAlreadyLinked: The nexus represented by the auth code specified is already a member of your group and has been linked with a different playerId. Allowed values: InvalidGroup, CodeNotInGroup, InvalidAuthCode, ExpiredAuthCode, NexusNotFound, PlayerNotInGroup, UnknownError, PlayerAlreadyLinked, MemberAlreadyLinked.
- `message` (string) - A human-readable explanation. Log it; do not match on it, as the wording can change. Branch on `code` instead.