Partner External ID Linking

This flow is for partners who need a trusted mapping between an AGG user.id and their own internal user ID for rewards, analytics, or reconciliation. The assertion must come from your backend, not from the browser.

The HMAC externalId is the durable partner user id. It is not the venue externalIdentifier and not the webhook partner id. See Ids.

How it works

Generate the app secret

Generate or rotate the app secret from the AGG admin dashboard, then store it in your backend secrets manager. Never expose it to the browser. The secret is hex.

Sign the assertion on your backend

Sign HMAC-SHA256 over the string {externalId}:{timestamp}. timestamp is an integer in milliseconds. The key is that hex secret decoded from hex, not the hex text as UTF-8. Send the hex digest as hmac. A timestamp more than five minutes off the server clock is rejected.

Send the assertion to the frontend

Return { externalId, timestamp, hmac } from your own API after the user is authenticated in your app.

Link it in AGG

Call client.linkExternalId(assertion) or the useExternalId() hook. AGG returns the updated UserProfile with externalId populated.

Webhook-assisted linking

If your backend needs to connect new AGG users to existing partner users, subscribe to accounts.created. The event includes the AGG userId and, when available from magic-link or OAuth sign-in, email. Use that email to resolve your internal user record, then complete the normal signed assertion flow for that authenticated user. After client.linkExternalId(assertion) succeeds, AGG emits accounts.linked with the AGG userId and your externalId.

import { parseWebhookEvent } from "@agg-build/sdk/server";

const event = parseWebhookEvent(rawBody, req.headers, process.env.AGG_WEBHOOK_SECRET!);

if (event.type === "accounts.created" && event.data.email) {
  const partnerUser = await users.findByEmail(event.data.email);
  if (partnerUser) {
    await pendingLinks.store({
      aggUserId: event.data.userId,
      externalId: partnerUser.id,
    });
  }
}

accounts.created.data.email is null when AGG does not have an email for the principal, such as wallet-only sign-in or OAuth providers that do not return email.

Examples

Backend signing

Node.js
Python

import { signExternalId } from "@agg-build/sdk/server";

// Example: partner user record from your own database/session
const externalId = currentPartnerUser.id;

const assertion = signExternalId(process.env.AGG_APP_SECRET!, externalId);

// Return this from your backend to your frontend
return assertion;

import hashlib
import hmac
import time

external_id = current_partner_user["id"]
timestamp = int(time.time() * 1000)
payload = f"{external_id}:{timestamp}".encode()

digest = hmac.new(
  bytes.fromhex(AGG_APP_SECRET),
  payload,
  hashlib.sha256,
).hexdigest()

assertion = {
  "externalId": external_id,
  "timestamp": timestamp,
  "hmac": digest,
}

Link the user

Send the assertion with the user’s access token. A 409 means that external id is already linked to another user in this app.

import { createAggClient } from "@agg-build/sdk";

const client = createAggClient({
  baseUrl: "https://api.agg.market",
  appId: "your-app-id",
});

// assertion comes from your backend
const profile = await client.linkExternalId(assertion);

curl -X POST https://api.agg.market/users/me/external-id \
  -H "x-app-id: $AGG_APP_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "externalId": "partner-user-123", "timestamp": 1712345678901, "hmac": "HEX_DIGEST" }'

Link partner external user ID (HMAC-verified).

import { useEffect, useRef } from "react";
import { useExternalId } from "@agg-build/hooks";

function LinkPartnerAccount({
  assertion,
}: {
  assertion: { externalId: string; timestamp: number; hmac: string } | null;
}) {
  const { linkExternalId } = useExternalId();
  const lastLinkedAssertion = useRef<string | null>(null);

  useEffect(() => {
    if (!assertion) return;

    const key = `${assertion.externalId}:${assertion.timestamp}`;
    if (lastLinkedAssertion.current === key) return;

    lastLinkedAssertion.current = key;

    void linkExternalId(assertion).catch(() => {
      lastLinkedAssertion.current = null;
    });
  }, [assertion, linkExternalId]);

  return null;
}

Once linked, externalId is returned on the updated UserProfile and on future client.getCurrentUser() calls.

Start here

Core concepts

Account

Trading

Venues

Market data

Security

Real-time

Webhooks

Your users

UI Kit

Releases

How it works

Webhook-assisted linking

Examples

Backend signing

Link the user

​How it works

​Webhook-assisted linking

​Examples

​Backend signing

​Link the user

How it works

Webhook-assisted linking

Examples

Backend signing

Link the user