User Onboarding (Production)

This is the ordered runbook for taking a freshly deployed Open Privacy Suite from "the stack is up" to "users can authenticate and transact with the right permissions." It assumes you have already completed Operator Deployment and the proxy-backend healthcheck is green.

Everything here drives the admin REST API with curl. The same operations are available in the admin dashboard UI, but the very first admin must be created over the API — you cannot log into the dashboard until a user exists and is in an admin group. For the concepts behind the commands (the 3-tier admin model, claims, the method allowlist), read RBAC first.

Before you start

You will need:

• ADMIN_API_TOKEN — the bootstrap super-admin secret you set at deploy time. It is sent as the X-Admin-Token header. Source it from your secret store; never hard-code it in a script that lands in a repo.
• The proxy backend URL as reachable from where you run curl — http://127.0.0.1:8080 on the host in a default prod compose.

# Pull the token from your secret store into the shell (example shape — adapt to
# AWS Secrets Manager / Vault / your CSI-mounted file). Do NOT echo it.
ADMIN_API_TOKEN="$(your-secret-fetch privacy-proxy/admin-api-token)"
PROXY=http://127.0.0.1:8080

Two ways to authenticate to the admin API

Tier-2 org admins normally use the dashboard UI — they obtain their JWT by logging in through Privado or Azure SSO like any user. Part 1 (bootstrap) is super-admin-only and uses X-Admin-Token; Part 2 onward is the org admin's job and uses their Authorization: Bearer token (the examples switch to it accordingly).

Who holds the super-admin token determines who runs the bootstrap

ADMIN_API_TOKEN is the only credential that can create orgs and mint org admins. Where it lives depends on how the Open Privacy Suite is operated for a given client — decide this up front, because it decides who runs Part 1:

In both models, Part 2 onward is the same and is done by tier-2 org admins — the difference is only who performs the one-time super-admin bootstrap and who custodies the token long-term. If the platform operator manages the token, the handoff point is Step 4 (the operator onboards the client's first admin by DID; from there the client is self-sufficient and never needs X-Admin-Token). Whoever holds it must source it from a secret store and rotate it per the credential-lifecycle guidance.

Part 1 — Bootstrap (super-admin, one time)

These four steps stand up the first tenant and hand it to a human org admin. They are super-admin-only — the org-creation and is_org_admin endpoints reject tier-2 JWTs by design (escalation prevention).

curl -sS -X POST "$PROXY/api/v1/admin/orgs" \
  -H "X-Admin-Token: $ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "acme", "name": "Acme Corporation" }'

ORG_ID="<id from the response>"

curl -sS -X POST "$PROXY/api/v1/admin/orgs/$ORG_ID/groups" \
  -H "X-Admin-Token: $ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "org-admins",
    "name": "Organization Admins",
    "is_org_admin": true
  }'

curl -sS -X PUT "$PROXY/api/v1/admin/orgs/$ORG_ID/groups/$ADMIN_GROUP_ID/access" \
  -H "X-Admin-Token: $ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_methods": [
      "eth_call", "eth_sendTransaction", "eth_estimateGas",
      "eth_getBalance", "eth_getCode", "eth_getTransactionCount",
      "eth_getTransactionReceipt", "eth_getLogs",
      "eth_blockNumber", "eth_chainId", "eth_gasPrice"
    ],
    "claims": []
  }'

curl -sS -X POST "$PROXY/api/v1/admin/orgs/$ORG_ID/memberships/by-did" \
  -H "X-Admin-Token: $ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:iden3:privado:main:2Sf...",
    "group_id": "'"$ADMIN_GROUP_ID"'"
  }'

Removing an org admin by DID (super-admin)

Removal is the symmetric counterpart of bootstrap step 4 — same identifier, same body shape, same scope rules:

curl -sS -X DELETE "$PROXY/api/v1/admin/orgs/$ORG_ID/memberships/by-did" \
  -H "X-Admin-Token: $ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:iden3:privado:main:2Sf...",
    "group_id": "'"$ADMIN_GROUP_ID"'"
  }'

What the operator credential can and cannot do here:

• Can: add a DID to, and remove a DID from, is_org_admin groups. Minting and revoking org admins is deliberately super-admin-only — a tier-2 org-admin JWT cannot mint or remove a peer who could then ban or demote them.
• Cannot: manage regular-group memberships with the operator token — that is per-org tenant management and is rejected; org admins do it themselves (Part 2). The operator token also cannot read tenant data (user lists, groups, contracts are tenant-confidential), which is why removal works purely from the DID and group id you already hold — no lookup step is required or possible.
• Opaque failures: an unknown DID, a DID with no membership in the target group, and a group belonging to a different org all return the same opaque 403. The API confirms nothing about what exists (no enumeration oracle) — if a removal unexpectedly 403s, re-check the DID and group id you recorded at onboarding time.

Audit attribution. Every mint and removal lands in the RBAC audit log, attributed to the credential that performed it: the full super-admin token as __super_admin__, the restricted operator/bootstrap token as __operator__, and a tenant org admin's JWT as that admin's own identity. Access reviews can therefore separate operator lifecycle actions from in-tenant administration.

Part 2 — Day-to-day onboarding

These are the tier-2 org admin's day-to-day operations, run with their session JWT — they manage their own org: groups, memberships, contract grants, KYC/ban. (Org creation and minting org admins are not here — those are the super-admin bootstrap in Part 1.)

# The org admin's session JWT, from logging in via Privado / Azure SSO.
# Short-lived — refresh when it expires. Sent as Authorization: Bearer below.
ADMIN_JWT="${PRIVACY_PROXY_ADMIN_JWT}"

Create the groups your users need

A group bundles a method allowlist with claims. Pick claims by the role you want:

These are the role-distinguishing methods only — every interactive group also needs the client baseline described in the callout below.

Create a deployer group, then set its access:

# Create
curl -sS -X POST "$PROXY/api/v1/admin/orgs/$ORG_ID/groups" \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{ "slug": "deployers", "name": "Contract Deployers" }'
# → capture group id as DEPLOY_GROUP_ID

# Set access (methods + claims)
curl -sS -X PUT "$PROXY/api/v1/admin/orgs/$ORG_ID/groups/$DEPLOY_GROUP_ID/access" \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{
    "allowed_methods": [
      "eth_call", "eth_sendTransaction", "eth_sendRawTransaction",
      "eth_estimateGas", "eth_getBalance", "eth_getCode",
      "eth_getTransactionCount", "eth_getTransactionReceipt",
      "eth_blockNumber", "eth_chainId", "eth_gasPrice",
      "eth_feeHistory", "eth_maxPriorityFeePerGas", "eth_getBlockByNumber"
    ],
    "claims": ["deploy"]
  }'

The /access body also accepts an optional per-group upstream rpc_api_key — see RBAC → Per-Group RPC API Keys. Which inbound header that key is read from is operator-wide (RPC_API_KEY_HEADER), not a per-group field. Request-rate limits are not set here; they come from the upstream RPC proxy's tier for that key.

Add users to groups

By DID (recommended). One call, auto-provisions a new user, idempotent on repeat (409 if already a member):

curl -sS -X POST "$PROXY/api/v1/admin/orgs/$ORG_ID/memberships/by-did" \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{ "did": "did:iden3:privado:main:2Sf...", "group_id": "'"$DEPLOY_GROUP_ID"'" }'

This is an ADD, not a move — it does not touch the user's default-group membership. To remove later, DELETE /api/v1/admin/users/:user_id/memberships/:membership_id.

By UUID (alternative). If you already have the user's UUID (e.g. from the dashboard):

# Find the UUID
curl -sS "$PROXY/api/v1/admin/users" -H "Authorization: Bearer $ADMIN_JWT"

# Add to a group (the target user must already be in your full-admin scope)
curl -sS -X POST "$PROXY/api/v1/admin/users/$USER_ID/memberships" \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{ "group_id": "'"$DEPLOY_GROUP_ID"'" }'

Set KYC / ban status

curl -sS -X PUT "$PROXY/api/v1/admin/users/$USER_ID" \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{ "kyc": true, "banned": false }'

A banned user is rejected at token-issuance time, so their memberships go dormant until the ban is lifted.

Part 3 — Grant contract access

All contracts are private by default. Standard users (anything but an org admin) see a registered contract only if their group has a contract grant for it. Contracts deployed through the proxy are auto-registered to the deployer's org; contracts that already exist on-chain must be registered first.

# Register an existing on-chain contract to the org (skip for proxy-deployed ones)
curl -sS -X POST "$PROXY/api/v1/admin/orgs/$ORG_ID/contracts" \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{ "address": "0xToken...", "name": "Acme USD" }'

# Grant a group access to it
curl -sS -X POST "$PROXY/api/v1/admin/orgs/$ORG_ID/contracts/0xToken.../grants" \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{ "group_id": "'"$DEPLOY_GROUP_ID"'" }'

Grant body fields:

• functions — omit / null for "all functions allowed", or a list of FunctionRule objects (with optional param_rules) to restrict to specific selectors.
• event_rules — omit / null = no events visible; "*" = all events; a list = an allowlist. Anything other than "no events" requires the contract to have an ABI (uploaded or a built-in token_type).

For the full function/event/parameter-constraint model and the two-step UI wizard, see RBAC → Granting access.

Connecting tools to the proxy

Two different surfaces, two different tools:

• The admin onboarding API in this runbook is plain REST, not JSON-RPC. cast speaks JSON-RPC, so it is not the tool for creating orgs/groups/memberships — those stay curl (or the dashboard).
• User interaction with the chain goes through the proxy's JSON-RPC endpoint. The proxy reads the user's session JWT from an Authorization: Bearer header (or the pp_access cookie), and for multi-org users expects the org-scoped path /rpc/<org_id>. Any tool that can attach that header can talk to the proxy.

cast attaches the bearer via --rpc-headers (or the ETH_RPC_HEADERS env var):

# A user's JWT (obtained from Privado/Azure login; the same access_token the
# dashboard uses). Source it securely — never hard-code it. Access tokens are
# short-lived (5 min); obtain a fresh one when it expires.
JWT="${PRIVACY_PROXY_USER_JWT}"
RPC="$PROXY/rpc"          # or /rpc/:org_id for multi-org users

# Read call through the proxy as that user. Pass --from with one of the
# user's own linked addresses: the proxy's eth_call path rejects any other
# `from`, and cast otherwise defaults it to the zero address — which comes
# back as "call denied: invalid request shape".
cast call 0xToken... "balanceOf(address)(uint256)" 0xUser... \
  --from 0xYourLinkedAddress... \
  --rpc-url "$RPC" --rpc-headers "Authorization: Bearer $JWT"

# Send a transaction through the proxy. cast builds an EIP-1559 tx by
# default, so it first calls eth_feeHistory + eth_maxPriorityFeePerGas to
# estimate fees — the sender's group must allowlist those (see the deployer
# group above). Add --legacy to price gas from eth_gasPrice and skip them.
# The tx is signed locally, so it reaches the proxy as eth_sendRawTransaction
# (access-checked as eth_sendTransaction).
cast send 0xToken... "transfer(address,uint256)" 0xRecipient... 1000 \
  --rpc-url "$RPC" --rpc-headers "Authorization: Bearer $JWT" \
  --private-key "$PK"

The proxy still enforces the full RBAC pipeline on these calls (method allowlist → contract access → redaction), so the JWT's group permissions decide what succeeds and what comes back redacted.

Part 4 — Verify

# Effective permissions for a user (what they can actually do)
curl -sS "$PROXY/api/v1/admin/users/$USER_ID/effective-permissions" \
  -H "Authorization: Bearer $ADMIN_JWT"

# Simulate a specific access decision without side effects. Mind the field
# names: the user is identified by user_external_id (their DID, not the UUID)
# and the contract by target_address; include org_id for multi-org users.
curl -sS -X POST "$PROXY/api/v1/admin/access/check" \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{ "user_external_id": "did:iden3:privado:main:2Sf...", "org_id": "'"$ORG_ID"'", "method": "eth_call", "target_address": "0xToken..." }'

Org admins can also use the dry-run / "what would this user see" endpoint to validate a user's view of a real RPC call. Finally, confirm the user can authenticate end-to-end by having them log in to the dashboard or explorer — or by making a read call through the proxy with their JWT (see Connecting tools to the proxy).

Day-1 checklist

[ ] ADMIN_API_TOKEN sourced from secret store; admin API reached from an allowed private-network source IP (token + IP gate)
[ ] Created the organization                          (POST /orgs)
[ ] Created the first org-admin group (is_org_admin)  (POST /orgs/:org/groups)   ← super-admin only
[ ] Set the admin group's method allowlist            (PUT  .../access, claims: [])
[ ] Onboarded the first human admin by DID            (POST .../memberships/by-did)
[ ] Created standard / deployer / trader groups        + set each group's access
[ ] Onboarded users into their groups                  (by-did)
[ ] Registered pre-existing contracts + granted groups (POST .../contracts, .../grants)
[ ] Verified effective-permissions and a live login
[ ] Confirmed audit logs are flowing to your SIEM      (see Audit Log Integrity)

Endpoint reference

All paths are prefixed /api/v1/admin. Day-to-day endpoints (Part 2+) are driven by the tier-2 org admin's Authorization: Bearer <JWT>; the platform/bootstrap endpoints (Part 1 — create org, mint org admins) use the super-admin X-Admin-Token. The per-row Auth column below says which is which. All are gated to private-network source IPs (the IP check described in Before you start).

Further reading

• RBAC — the permission model, claims hierarchy, contract grants, and the dashboard walkthrough.
• Operator Deployment — bringing the stack up, required secrets (including ADMIN_API_TOKEN), and the super-admin maintenance endpoints.
• Authentication and Azure AD / SSO — how users (and admins) obtain the session JWT referenced above.
• API Reference — full request/response shapes for every endpoint.
• Audit Log Integrity — every onboarding writes a tamper-evident audit row; forward it to your SIEM.