Tenants
A tenant is one customer of DiligenceID. Everything you create belongs to exactly one, and nothing crosses between them.
How a tenant is established
From your API key. Never from a header, a body field or a query parameter, even when one exists that appears to name a tenant.
This matters more than it looks. If a tenant could be named in a request, then any bug that let an attacker control that field would be a cross-tenant read. Deriving it from the credential means there is no field to attack.
A request that cannot resolve a tenant fails. There is no fallback and no default tenant.
What isolation means
Every query is tenant-scoped at the point it is issued, not filtered afterwards. Organisations, issuers, credential configurations, verification policies, transactions and verifications are all tenant-owned.
Non-disclosure
A request for a resource in another tenant returns 404 Not Found, not 403 Forbidden.
This is deliberate. A 403 says "this exists and you may not have it", which is a disclosure: an attacker could enumerate valid identifiers by watching which ones return 403 and which return 404. A uniform 404 tells them nothing.
The same applies across environments. A Sandbox key asking for a Production issuer gets 404, not 403.
Do not read a 404 as proof a resource does not exist anywhere. It means it does not exist for you.
Tenants and organisations
They are different things and easy to confuse.
A tenant is the DiligenceID customer — a billing and isolation boundary.
An organisation is a legal entity credentials are issued on behalf of. A tenant may have several: a services group with distinct subsidiaries, each issuing under its own name.
Organisations are inside a tenant. They are not an isolation boundary between customers.