SynqDocs
Guides

Authorizing by wallet

Let your API check, from the access token alone, that the wallet in a request is one of the signed-in person's wallets.

Many Solana APIs key what they keep by wallet. Say Acme Guild's API has PATCH /v1/profiles/{wallet}, which changes the profile of one wallet. Before it changes anything, it has to know the wallet in the path is the caller's. Turn on the wallets claim for your API, and every access token Synq issues for it lists the person's wallets: the check needs no management key, no call to Synq per request and no signed message from the wallet.

Turn the claim on

In the dashboard, tick Wallets under What it learns about people on your API's page, and save. Or add wallets to your API's identity_claims (change an API, with org.apis.edit), beside any it already has. $SYNQ_API here is the management API, https://api.synq.build:

curl -X PATCH "$SYNQ_API/v1/orgs/$ORG/brands/$BRAND/apis/$API" \
  -H "Authorization: Bearer $SYNQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "identity_claims": ["wallets"] }'

With your agent, the MCP server's request_configuration_change does it (update_api, with identity_claims). From the next token on, each one carries wallets: an empty list for someone with no wallet, so your API can tell "none" from "not asked for".

A wallet's address is personal data: it ties the person to everything the address did on chain. Turn the claim on only for an API that authorizes or keys by wallet. Your brand's own apps get tokens with it at once; an app that isn't the brand's own gets one only after the person allows it on the consent page, which names it ("Acme Guild API sees your wallet addresses, and which is your primary one").

Check the wallet on your API

createAccessTokenVerifier from @synqauth/js/server checks the token, and ownsWallet checks the wallet against its claim. The route below works anywhere a handler takes a Request (a Next.js route handler, Hono, a Worker):

import { createAccessTokenVerifier, isSynqError, ownsWallet } from '@synqauth/js/server'

const verify = createAccessTokenVerifier({
  issuer: process.env.SYNQ_ISSUER!,
  audience: 'https://api.acmeguild.com',
})

export async function updateProfile(request: Request, wallet: string): Promise<Response> {
  let claims
  try {
    const token = request.headers.get('authorization')?.replace(/^Bearer /, '') ?? ''
    claims = await verify(token, { scopes: ['profiles:write'] })
  } catch (error) {
    if (isSynqError(error))
      return Response.json({ error: error.code }, { status: error.status ?? 401 })
    throw error
  }
  if (!ownsWallet(claims, wallet)) {
    return Response.json({ error: 'not_your_wallet' }, { status: 403 })
  }
  // The wallet is the caller's: change its profile, keyed by `wallet` as before.
  return Response.json(await saveProfile(wallet, await request.json()))
}

ownsWallet compares the address exactly, as base58 is case-sensitive, and on Solana unless you name another chain ({ chain }). It answers false for a token without the claim, so a route never opens by mistake on an API that didn't turn it on. primaryWallet(claims) gives the person's primary wallet, for an API that acts on one wallet by default.

A route that takes your users' API keys too checks a key's claims the same way: createApiKeyVerifier's answer carries wallets, read when the key is checked.

Someone with more than 10 wallets

A token lists at most 10 wallets: the primary one, then the ones signed in with most recently. When the person has more, the token says wallets_truncated: true (walletsTruncated(claims)), and a wallet missing from it may still be theirs. Before refusing such a token, read the person's wallets live: on your server, a user's details in the management API (org.users.view) list every identity, wallets among them.

if (!ownsWallet(claims, wallet)) {
  if (!claims.wallets_truncated) return Response.json({ error: 'not_your_wallet' }, { status: 403 })
  if (!(await walletsLive(claims.sub)).includes(wallet)) {
    return Response.json({ error: 'not_your_wallet' }, { status: 403 })
  }
}

walletsLive is yours: it calls the management API with an org API key your server keeps, and is needed only for someone who has more than 10.

How fresh it is

A token's wallets are read when it's made, a refresh included. A wallet the person removes from their account, or moves to another account, is gone from their next token, and a token lives as long as your API's access_token_ttl (5 to 15 minutes; 10 unless you chose otherwise). So for up to that long after a removal, a token issued before it still lists the wallet. Where that matters, such as moving value out of a wallet's account, give the API the shortest lifetime (300 seconds), or read the wallets live as above.

In your app

An app reads the same list for display with the wallets scope: at most 10 in the ID token (user.wallets in @synqauth/nextjs and @synqauth/react), and every one at userinfo, read when asked. The profile's own list, with each wallet's label and the wallet app that last signed with it, is the account API's list of wallets (Connected wallets). Tokens and claims has the claim's every field.

On this page