Link a nexus

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

required

stringheader

Send your secret API key (nexus_sk_...) in the X-SHARED-SECRET header. Generate one in the Publisher Dashboard.

Parameters

Query Parameters

groupId

string

Example

V1StGXR8_Z5jdHi6B1LiO

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

object

playerId

required

Your identifier for the player to associate with the linked Nexus account.

string

Example

player_8f2c41d0

authCode

required

The auth code the creator gave you, from generateAuthCode. Expires 30 minutes after issuance and can only be redeemed once.

string

Example

028-311

playerMetadata

Additional player information to be applied to this member (such as their in game display name)

object

displayName

The players in game display name

string

Example

Popcorn Frog

Responses

200

Referral code of linked Nexus

application/json

object

groupId

ID of the creator group

string

groupName

Name of the creator group

string

The linked member’s Nexus id.

string

playerId

Unique identifier for user that was linked to the Nexus represented by the specified authCode

string

codes

Array<object>

A group member’s code which is used as their storefront URL and when creating transactions or referrals

object

code

string

isPrimary

Indicates whether or not this is the primary code for this member.

boolean

isGenerated

Indicates whether or not this is a code that you generated.

boolean

isManaged

Indicates whether or not this is a code that you manage. Once a code that you generated has been linked to a Nexus account, it will no longer be considered managed.

boolean

400

Bad request

application/json

object

code

CodeNotInGroup: Creator group is private, and specified code is not linked to it
InvalidGroup: No creator group was found with the specified groupId
InvalidAuthCode: AuthCode provided is not valid or the nexus it represents is not a member of your program
ExpiredAuthCode: AuchCode provided has expired
NexusNotFound: No Nexus was found to match the provided code
PlayerNotInGroup: No group member found for the given playerId
PlayerAlreadyLinked: The playerId provided has already been linked with a group member
MemberAlreadyLinked: The nexus represented by the auth code specified is already a member of your group and has been linked with a different playerId.

string

Allowed values: InvalidGroup CodeNotInGroup InvalidAuthCode ExpiredAuthCode NexusNotFound PlayerNotInGroup UnknownError PlayerAlreadyLinked MemberAlreadyLinked

message

A human-readable explanation. Log it; do not match on it, as the wording can change. Branch on code instead.

string

POST

/manage/members/link

const url = 'https://api.nexus.gg/v1/manage/members/link?groupId=V1StGXR8_Z5jdHi6B1LiO';
const options = {
  method: 'POST',
  headers: {
    'X-SHARED-SECRET': 'nexus_sk_your_key_here',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({playerId: 'player_8f2c41d0', authCode: '028-311', displayName: 'Popcorn Frog'})
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://api.nexus.gg/v1/manage/members/link?groupId=V1StGXR8_Z5jdHi6B1LiO' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'X-SHARED-SECRET: nexus_sk_your_key_here' \
  --data playerId=player_8f2c41d0 \
  --data authCode=028-311 \
  --data 'displayName=Popcorn Frog'

Example

{
  "groupId": "V1StGXR8_Z5jdHi6B1LiO",
  "groupName": "Aurora Drift Creators",
  "id": "CsRKC8uD0NLtyQ0LOt8Ru",
  "playerId": "player_8f2c41d0",
  "codes": [
    {
      "code": "samzorz",
      "isPrimary": true,
      "isGenerated": false,
      "isManaged": false
    }
  ]
}

Example

{
  "code": "InvalidGroup",
  "message": "Invalid Group ID: V1StGXR8_Z5jdHi6B1LiO"
}