GET/v1/partner/end_users/{external_id}

Get end user

Returns the full profile for a single end user: their Yieldforce-internal id, external_id, tenant context, wallet address, and creation timestamp. Supports both Entra (Entra token only) and user-scoped (Entra + user token). In user-scoped the X-User-Token's sub claim must match the external_id in the URL.

Use this endpoint to confirm that a user has been successfully created, or to retrieve the provisioned wallet_address for display in your UI.

Path parameters

external_idstringrequired

Your stable identifier for the user. Must match the sub claim of the X-User-Token when using user-scoped.

Headers

Authorizationstringrequired

Entra M2M access token. Format: Bearer <token>. See Entra authentication.

X-User-Tokenstringoptional

Partner-minted JWT for the end user. Required in user-scoped (user-initiated context). The sub claim must equal external_id. See User authentication.

Example request

const baseUrl = process.env.YIELDFORCE_API_BASE_URL ?? 'https://yieldforce.io/api';
 
const res = await fetch(`${baseUrl}/v1/partner/end_users/alice-bunq-id`, {
  headers: {
    Authorization: `Bearer ${entraToken}`,
    'X-User-Token': partnerJwt, // required in user-scoped
  },
});
const data = await res.json();

Response

200 End user profile

{
  "id": "usr_01HZ4KXQM5E8WRTYN3P7VBJD6F",
  "external_id": "alice-bunq-id",
  "tenant_id": "tnt_01HZ4KXQM5ABCDEF12345678",
  "tenant_slug": "bunq",
  "user_source": "partner",
  "wallet_address": "0xabc123...def456",
  "created_at": "2026-05-20T10:00:00.000Z"
}

Errors

401 token_missing — No Authorization: Bearer header on the request.

401 invalid_entra_token — Token is expired, malformed, or has an unexpected audience.

401 invalid_user_token — The X-User-Token failed signature verification or is expired.

403 sub_url_mismatch — The sub claim in X-User-Token does not match external_id in the URL.

404 end_user_not_found — No user with this external_id exists in your tenant, or the user has been deleted.