This guide explains how workspaces, projects, team members, and API keys are organized in Vilna. For endpoint details, see the API Reference. For roles and permissions, see Authorization.
Everything in Vilna is organized under workspaces:
- A workspace is the top-level unit. Each user can create up to 5 workspaces.
- Projects live inside a workspace and provide data isolation - each project has its own monitored addresses, transactions, and API keys.
- Members are users with access to the workspace. They are added through invitations.
- API keys are scoped to a project. RPC keys and management keys are scoped to the workspace.
Vilna uses three types of API keys, each with a distinct prefix and scope:
| Type | Prefix | Scope | What it accesses |
|---|---|---|---|
| API key | vilna_api_ | Project | Platform API - addresses, transactions, balances, events, invoices |
| RPC key | vilna_rpc_ | Workspace | Blockchain RPC - JSON-RPC and gRPC node access |
| Management key | vilna_mgt_ | Workspace | Management API - workspaces, members, projects, keys |
Each key carries an embedded set of permissions. When you create a key, you specify which permissions it should have. The key can only perform actions within its granted permissions.
The raw key value is returned only once at creation. It cannot be retrieved again. Store it in a secret manager or environment variable immediately.
New team members join a workspace through email invitations. The flow:
- An admin creates an invitation for an email address with a role (
adminormember). - The invitee receives the invitation and can accept or decline.
- On acceptance, the user becomes a workspace member with the assigned role.
- Pending invitations can be revoked by any admin.
| Status | Meaning |
|---|---|
pending | Invitation sent, waiting for response |
accepted | User accepted and became a member |
declined | User declined the invitation |
revoked | An admin cancelled the invitation |
A workspace must retain at least one admin at all times. Removing the last admin or demoting them to member is rejected.
To rotate an API key without downtime:
- Create a new key with the same permissions.
- Update your application to use the new key.
- Verify the new key works in production.
- Revoke the old key.
The same process applies to RPC keys and management keys.
- Create a project in your workspace (via dashboard or API).
- Create an API key for the project with the permissions your application needs.
- Use the API key in the
X-Api-Keyheader to access the Platform API.
- Send an invitation to the user's email.
- Once accepted, assign the member to specific projects if their role is
member(admins see all projects automatically). - The member can now access the workspace through the dashboard.
If your platform serves multiple customers, you can automate the setup for each one:
- Create a project per customer.
- Generate API keys programmatically for each project.
- Distribute keys securely to each customer's integration.
This is the pattern used by exchanges, payment platforms, and other platforms that manage multiple isolated environments. See the API Reference for endpoint details.