Platform Users API

Platform user routes let operators provision users across tenants, resolve identity records, and attach immutable tenant-scoped wallet external IDs. They require a platform key and route scopes when scoped platform keys are enabled.

curl http://localhost:3200/platform/users/lookup \
  -H "X-Steward-Platform-Key: your-platform-key"

Platform User Object

{
  userId: string;
  email: string | null;
  emailVerified: boolean | null;
  name: string | null;
  image: string | null;
  walletAddress: string | null;
  walletChain: string | null;
  customMetadata: Record<string, unknown>;
  deactivatedAt: string | null;
  createdAt: string;
  updatedAt: string;
  tenantIds: string[];
  linkedAccounts: Array<{
    id: string;
    provider: string;
    providerAccountId: string;
    expiresAt: number | null;
  }>;
  walletExternalIds: Array<{
    tenantId: string;
    externalId: string;
  }>;
}

Wallet external IDs are write-once per user and tenant. Once assigned, the value cannot be changed to a different external ID for that same user in that tenant.

Create or Pre-Provision User

Creates a user record without sending email or requiring an interactive login. If the email already exists, Steward returns the existing user with isNew: false.

POST /platform/users

Auth: Platform key with platform:user:write Request Body:

{
  email: string;
  emailVerified?: boolean;
  name?: string;
  customMetadata?: Record<string, unknown>;
  tenantId?: string;
  walletExternalId?: string; // or externalId
}

When walletExternalId is supplied, tenantId is required. Steward links the user into that tenant and assigns the immutable wallet external ID in the same operation.

const user = await steward.platformUsers.create({
  email: "ada@example.com",
  emailVerified: true,
  tenantId: "app-prod",
  walletExternalId: "wallet_ada_001",
});

curl -X POST http://localhost:3200/platform/users \
  -H "X-Steward-Platform-Key: your-platform-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "emailVerified": true,
    "tenantId": "app-prod",
    "walletExternalId": "wallet_ada_001"
  }'

Response:

{
  "ok": true,
  "data": {
    "userId": "usr_123",
    "isNew": true,
    "tenantId": "app-prod",
    "walletExternalId": "wallet_ada_001"
  }
}

Lookup User

Looks up a user by a supported identity. walletExternalId lookup requires tenantId because external IDs are tenant-scoped.

GET /platform/users/lookup

Auth: Platform key with platform:user:read Query Parameters:

{
  email?: string;
  phone?: string;          // E.164
  walletAddress?: string;
  walletExternalId?: string;
  smartWalletId?: string;
  customAuthId?: string;
  provider?: string;
  providerAccountId?: string;
  tenantId?: string;
}

const { user } = await steward.platformUsers.lookup({
  tenantId: "app-prod",
  walletExternalId: "wallet_ada_001",
});

const sameUser = await steward.platformUsers.getUserByWalletExternalId(
  "wallet_ada_001",
  { tenantId: "app-prod" }
);

curl "http://localhost:3200/platform/users/lookup?tenantId=app-prod&walletExternalId=wallet_ada_001" \
  -H "X-Steward-Platform-Key: your-platform-key"

Response:

{
  "ok": true,
  "data": {
    "user": {
      "userId": "usr_123",
      "tenantIds": ["app-prod"],
      "linkedAccounts": [],
      "walletExternalIds": [
        { "tenantId": "app-prod", "externalId": "wallet_ada_001" }
      ]
    }
  }
}

Lookup Aliases

These POST aliases accept JSON bodies and return the same shape as GET /platform/users/lookup.

Endpoint	Body
`POST /platform/users/email/address`	`{ "email": string, "tenantId"?: string }`
`POST /platform/users/phone/number`	`{ "phone": string, "tenantId"?: string }`
`POST /platform/users/wallet/address`	`{ "walletAddress": string, "tenantId"?: string }`
`POST /platform/users/wallet/external-id`	`{ "walletExternalId": string, "tenantId": string }`
`POST /platform/users/smart-wallet/address`	`{ "smartWalletId": string, "tenantId"?: string }`

Assign Wallet External ID

Assigns a write-once wallet external ID to an existing user in a tenant.

POST /platform/users/:userId/wallet/external-id

Auth: Platform key with platform:user:write

{
  tenantId: string;
  walletExternalId: string; // or externalId
}

await steward.platformUsers.assignWalletExternalId("usr_123", {
  tenantId: "app-prod",
  walletExternalId: "wallet_ada_001",
});

curl -X POST http://localhost:3200/platform/users/usr_123/wallet/external-id \
  -H "X-Steward-Platform-Key: your-platform-key" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "app-prod", "walletExternalId": "wallet_ada_001" }'

Conflicts return 409 when the external ID belongs to another user in the same tenant or when the target user already has a different external ID in that tenant.

Resolve Wallet External ID

Resolves a tenant-scoped wallet external ID.

POST /platform/users/wallet/external-id

Auth: Platform key with platform:user:read

{
  tenantId: string;
  walletExternalId: string; // or externalId
}

const { user } = await steward.platformUsers.resolveWalletExternalId({
  tenantId: "app-prod",
  walletExternalId: "wallet_ada_001",
});

curl -X POST http://localhost:3200/platform/users/wallet/external-id \
  -H "X-Steward-Platform-Key: your-platform-key" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "app-prod", "walletExternalId": "wallet_ada_001" }'

Connect or Create by Wallet External ID

Resolves a wallet external ID to an existing user. If no mapping exists, Steward can create a user or connect an existing email user to the tenant, then assign the external ID.

POST /platform/users/wallet/external-id/connect-or-create

Auth: Platform key with platform:user:write

{
  tenantId: string;
  walletExternalId: string; // or externalId
  email?: string;
  emailVerified?: boolean;
  name?: string;
  customMetadata?: Record<string, unknown>;
  role?: "owner" | "admin" | "member";
}

const result = await steward.platformUsers.connectOrCreateByWalletExternalId({
  tenantId: "app-prod",
  walletExternalId: "wallet_ada_001",
  email: "ada@example.com",
  emailVerified: true,
});

curl -X POST http://localhost:3200/platform/users/wallet/external-id/connect-or-create \
  -H "X-Steward-Platform-Key: your-platform-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "app-prod",
    "walletExternalId": "wallet_ada_001",
    "email": "ada@example.com",
    "emailVerified": true
  }'

Response:

{
  "ok": true,
  "data": {
    "userId": "usr_123",
    "isNew": false,
    "createdExternalId": true,
    "tenantId": "app-prod",
    "walletExternalId": "wallet_ada_001",
    "user": {
      "userId": "usr_123",
      "tenantIds": ["app-prod"],
      "walletExternalIds": [
        { "tenantId": "app-prod", "externalId": "wallet_ada_001" }
      ]
    }
  }
}

Search Tenant Users by External ID

Tenant-scoped user search supports direct wallet external ID filtering.

GET /platform/tenants/:tenantId/users?walletExternalId=wallet_ada_001

Auth: Platform key with platform:tenant-user:read

const result = await steward.platformUsers.search("app-prod", {
  walletExternalId: "wallet_ada_001",
});

curl "http://localhost:3200/platform/tenants/app-prod/users?walletExternalId=wallet_ada_001" \
  -H "X-Steward-Platform-Key: your-platform-key"

Tenant admins with a user session can use the same filter through the user-authenticated directory route:

SDK

const result = await steward.listTenantUsers("app-prod", {
  walletExternalId: "wallet_ada_001",
});

Third-Party Wallet Policy Violations

When restrictToOneThirdPartyWallet is enabled after existing users already linked multiple EVM/Solana third-party wallets, tenant admins can review the violation report and remove one selected wallet from a tenant member.

GET /user/me/tenants/:tenantId/users/wallet-policy/violations

Auth: User bearer token for a tenant admin, with recent MFA.

const report = await steward.getTenantWalletPolicyViolations("app-prod", {
  limit: 50,
});

curl "http://localhost:3200/user/me/tenants/app-prod/users/wallet-policy/violations?limit=50" \
  -H "Authorization: Bearer user-session-jwt"

Response:

{
  "ok": true,
  "data": {
    "tenantId": "app-prod",
    "policyEnabled": true,
    "violations": [
      {
        "userId": "usr_123",
        "email": "ada@example.com",
        "name": "Ada",
        "role": "member",
        "walletCount": 2,
        "wallets": [
          {
            "accountId": "acct_1",
            "provider": "wallet:ethereum",
            "providerAccountId": "0x1111111111111111111111111111111111111111"
          },
          {
            "accountId": "acct_2",
            "provider": "wallet:solana",
            "providerAccountId": "So11111111111111111111111111111111111111112"
          }
        ]
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

The report is read-only. Use the remediation endpoint below when an owner/admin has chosen the wallet identity to remove.

Remediate a Violation

DELETE /user/me/tenants/:tenantId/users/:userId/wallet-policy/wallets/:accountId

Auth: User bearer token for a tenant owner/admin, with recent MFA and a session scoped to the tenant. The endpoint only removes linked EVM/Solana third-party wallets, refuses to remove the user’s last remaining login method, revokes the remediated user’s refresh tokens, writes authorized and final audit events, and sends a redacted user.unlinked_account webhook.

const result = await steward.remediateTenantWalletPolicyViolation(
  "app-prod",
  "usr_123",
  "acct_2",
);

curl -X DELETE \
  "http://localhost:3200/user/me/tenants/app-prod/users/usr_123/wallet-policy/wallets/acct_2" \
  -H "Authorization: Bearer user-session-jwt"

Response:

{
  "ok": true,
  "data": {
    "deleted": true,
    "accountId": "acct_2",
    "provider": "wallet:solana",
    "providerAccountId": "So11111111111111111111111111111111111111112",
    "issuedBefore": 1780613242000
  }
}

Bulk Remediate Violations

POST /user/me/tenants/:tenantId/users/wallet-policy/remediations

Auth: User bearer token for a tenant owner/admin, with recent MFA and a session scoped to the tenant. The request accepts up to 50 selected wallet accounts. Each item is processed with the same checks as the single-wallet endpoint: tenant membership, EVM or Solana wallet provider, last-login-method protection, refresh-token revocation, authorized/final audit events, and redacted user.unlinked_account webhooks. The response is intentionally per-item so operators can retry only failed selections.

const result = await steward.bulkRemediateTenantWalletPolicyViolations(
  "app-prod",
  [
    { userId: "usr_123", accountId: "acct_2" },
    { userId: "usr_456", accountId: "acct_7" },
  ],
);

curl -X POST \
  "http://localhost:3200/user/me/tenants/app-prod/users/wallet-policy/remediations" \
  -H "Authorization: Bearer user-session-jwt" \
  -H "Content-Type: application/json" \
  -d '{"wallets":[{"userId":"usr_123","accountId":"acct_2"},{"userId":"usr_456","accountId":"acct_7"}]}'

Response:

{
  "ok": true,
  "data": {
    "tenantId": "app-prod",
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "ok": true,
        "targetUserId": "usr_123",
        "deleted": true,
        "accountId": "acct_2",
        "provider": "wallet:solana",
        "providerAccountId": "So11111111111111111111111111111111111111112",
        "issuedBefore": 1780613242
      },
      {
        "ok": false,
        "targetUserId": "usr_456",
        "accountId": "acct_7",
        "status": 409,
        "error": "Cannot unlink the user's last login method"
      }
    ]
  }
}

Wallet External ID Rules

tenantId is required for wallet external ID lookup and assignment.
External IDs are trimmed, validated, and tenant-scoped.
The same external ID cannot belong to multiple users in one tenant.
A user cannot replace an existing wallet external ID with a different value in the same tenant.
The reserved backing provider used to store wallet external IDs is hidden from linkedAccounts and exposed through walletExternalIds.

​Platform Users API

​Platform User Object

​Create or Pre-Provision User

​Lookup User

​Lookup Aliases

​Assign Wallet External ID

​Resolve Wallet External ID

​Connect or Create by Wallet External ID

​Search Tenant Users by External ID

​Third-Party Wallet Policy Violations

​Remediate a Violation

​Bulk Remediate Violations

​Wallet External ID Rules

Platform Users API

Platform User Object

Create or Pre-Provision User

Lookup User

Lookup Aliases

Assign Wallet External ID

Resolve Wallet External ID

Connect or Create by Wallet External ID

Search Tenant Users by External ID

Third-Party Wallet Policy Violations

Remediate a Violation

Bulk Remediate Violations

Wallet External ID Rules