Tenants and Workspaces

XKOVA isolates each institution at two levels. A tenant is the institution itself, and a workspace is an operational scope inside it. Isolation is enforced in the database, so one tenant can never read another tenant's data, and one workspace's operational data stays inside that workspace.

Tenant: the institution

A tenant is the institution using XKOVA, for example a bank, a credit union, or a fintech. The tenant scope owns the things that belong to the institution as a whole: identity and member directory, billing, staff, branding, and compliance policy. Each tenant is provisioned with a sandbox sibling automatically, so every institution has both a sandbox and a production environment. See Supported Networks for how those environments map to chains.

Workspace: the operational scope

A workspace is the scope inside a tenant where day to day operations live. Operational data such as payments, escrows, treasury, wallets, fees, and member sessions is scoped to a workspace. A workspace is pinned to one chain at onboarding, which is why a sandbox workspace pins a testnet chain and a production workspace pins a mainnet chain. A fresh workspace is also provisioned with a seeded governance baseline: owner approval is required on its highest impact actions until the owner tunes those requirements. See Policies and Quorum Governance.

Scope	What lives here
Tenant	Member identity, billing, staff, branding, compliance policy.
Workspace	Payments, escrows, treasury, wallets, fees, member sessions.

Workspace Enabled Tokens

Each workspace keeps an allowlist of the token deployments it is allowed to transact in. Payments and transfers may only name a token that is on this list. A create call that names a token deployment the workspace has not enabled is rejected with token_not_enabled (422). Because the allowlist is a per-workspace configuration, these calls operate on the workspace pinned by the calling API key.

A token deployment can only be enabled on a workspace whose chain matches the deployment's chain, which keeps a testnet token off a mainnet workspace and the reverse. That chain match is checked when you enable, and enforced again in the database. See Supported Networks for how a workspace pins its chain.

Operation	Call	Effect
List enabled	GET /v1/workspace-tokens	Returns the tokens currently enabled on the workspace.
Discover available	GET /v1/workspace-tokens/available	Returns every token eligible for the workspace with an enabled flag, so you can render a toggle list.
Add	POST /v1/workspace-tokens	Enables a token deployment on the workspace.
Remove	DELETE /v1/workspace-tokens/{id}	Disables a token deployment on the workspace.

List Enabled Tokens

GET /v1/workspace-tokens returns { "data": [ ... ] }, one record per token currently enabled on the workspace. Each record carries id, workspace_id, token_deployment_id, enabled_at, and enabled_by_staff_id (the staff member who enabled it, or null when it was enabled by an integrator key).

Discover Available Tokens

GET /v1/workspace-tokens/available returns every token deployment eligible for the workspace, which is every deployment on the workspace's chain, joined with the workspace's enabled tokens so each row carries an enabled flag. Use it to render an enable and disable list without a second lookup. Each row carries token_deployment_id, token_symbol, token_name, contract_ref, decimals, permit_strategy, enabled, and workspace_token_id (the enabled record's id, or null when the token is not enabled).

The permit_strategy describes how a wallet authorizes the token's transfer in a signed meta transaction: eip2612 is the token's native permit, permit2 is a reserved path that is not yet wired, and none means neither is supported.

Add a Token

POST /v1/workspace-tokens with a body of { "token_deployment_id": "..." } enables the token and returns 201 with the enabled record. Enabling is idempotent: enabling a token that is already enabled returns the existing record rather than creating a second one, so the call is safe to retry. See Idempotency for making the call safe under an idempotency key. If the token deployment is on a different chain than the workspace, the call is rejected with validation_failed (422); if the deployment id does not exist, the call returns not_found.

Remove a Token

DELETE /v1/workspace-tokens/{id} disables the token and returns 204. This is a soft delete: the token is removed from the allowlist so it can no longer be selected for new payments or transfers, but the underlying record is retained so audit history stays intact. Enabling the same token again later creates a fresh record. Deleting a token that is not enabled returns not_found.

Database enforced isolation

Isolation is not a convention applied in application code. It is enforced in the database itself. Every request runs under the scope it is authorized for: a tenant-scoped request under its tenant and workspace, a partner-scoped request at the partner level. The database rejects reads or writes outside that scope. A workspace scoped key always gets strict workspace isolation, and the tenant boundary always holds on top of that, so cross tenant access is impossible even when something else goes wrong.

How keys map to scope

An integrator authenticates with a tenant API key that is pinned to a workspace, so its calls operate inside one workspace. A partner that manages many tenants can use a partner scope key to act across the tenants under it. Operators sign in to the console with a session scoped to their tenant.

• Authentication: API keys, bearer sessions, and federated or bring your own identity.
• Authorization and RBAC: roles, permissions, and how partner scope differs from tenant scope.

Related

For where these scopes come from when you first set up, see Operator Onboarding. For the actors that operate within a tenant, see the Platform Overview.