Skip to main content

PII Access Control

Overview​

Zyphe applies role-based access control (RBAC) to Personally Identifiable Information (PII) so that sensitive customer data is only visible to the people who need it. This page explains the principles behind that model. For the concrete roles and the exact permission matrix (who can do what in the dashboard and API), see Manage Users.

Problem statement​

In many KYC/KYB systems, everyone with dashboard access can see every customer's PII. That creates avoidable risk:

  • Insider threat: internal actors with legitimate access can exfiltrate large volumes of sensitive data.
  • Over-privileged access: people with no need to view PII can see it anyway.
  • Compliance risk: broad access makes data-minimization obligations under GDPR, CCPA, and similar regimes hard to meet.
  • Weak audit trail: without granular controls it is difficult to reconstruct who accessed what, and when.

How Zyphe reduces PII exposure​

Zyphe addresses this on two fronts:

  1. Decentralized storage. PII lives in the user's own vault, not in a central Zyphe database. Only the minimum attributes required for a given operation are read, and every access is recorded in a hash-chained audit trail. See Decentralized Identity and Why decentralized PII storage.
  2. Role-based access. Within your organization, what each member can see and do is governed by their role. Roles are least-privilege by default: a member is granted the narrowest set of permissions that lets them do their job, and elevated access is the exception rather than the rule.

Roles​

Access is governed by the organization roles Zyphe enforces today:

RoleTypical use
AdminOrganizational management and oversight; full access.
OperatorReviewing and operating on verification results and AML cases.
AML OfficerAML monitoring and case management.
DeveloperIntegration work, flows, API keys, webhooks.
PartnerExternal collaborators, limited to flows explicitly shared with them.

The authoritative, per-permission breakdown of these roles, including what each can access and how partner flow access is granted, is maintained in Manage Users. Treat that page as the single source of truth; this page covers only the principles.

Least privilege in practice

Default new members to the lowest role that lets them work, review elevated roles periodically, and keep the number of full-access accounts small. Grant broader access deliberately, not by default.

Non-human access​

Agents and API credentials are members of your organization too: each one is created with a role and can do exactly what a person holding that role can do, no more. Their actions are recorded in the audit trail under their own name. Agents cannot hold the Partner role, and API credentials cannot manage people, credentials or billing. See Agents and API credentials.

Strong authentication​

Members sign in with a password, a magic link or a passkey. Admins can require two-factor authentication of every member, so a stolen password alone does not open the dashboard, and can reset a member's second factor when it is lost.

Exporting personal data​

Downloading a KYC result from the dashboard (Download PDF or Download JSON) takes the personal data out of Zyphe's controls. Before the download, the member must confirm that they understand the export contains personal information and accept full liability for any breach involving it. Only members whose role can read the result can download it.

Webhooks and PII​

There is no PII level to choose for webhooks. A delivery carries statuses, identifiers and the outcome of each step, plus the personal attributes some steps return by nature (the identity's email when known, the attributes of a SPID / CIE login, a verified wallet address); it never carries identity-document images. Fetch document data and media separately, from your backend, with the Export API, and treat every delivery as personal data. See Webhook payload.

The one exception is the extended DV payload on a webhook endpoint, which adds the fields extracted from the document and a time-limited selfie URL. It is not offered on new endpoints: it exists only on endpoints carried over from an older configuration, or enabled by Zyphe support. If an endpoint carries it, treat that endpoint's deliveries as personal data. See Webhook Endpoints and Backwards Compatibility.

Best practices​

For organizations

  1. Assign full-access (Admin) roles sparingly, and require two-factor authentication of every member.
  2. Review who holds elevated roles on a regular cadence.
  3. Monitor for unusual access patterns.
  4. Default to the least-privileged role and grant more only when there is a demonstrated need, for agents and API credentials as much as for people.

For developers

  1. Never cache PII in client-side storage or logs.
  2. Check access on every request rather than assuming it from a previous one.
  3. Handle missing PII gracefully, your UI should work when PII fields are absent for the current role.
  4. Test your integration against every role your users may have.

Support​

For questions about PII access control, contact support@zyphe.com.