# Management API Guide

This guide explains how workspaces, projects, team members, and API keys are organized in Vilna. For endpoint details, see the [API Reference](/apis/mgmt/api). For roles and permissions, see [Authorization](/apis/mgmt/authorization).

## Resource hierarchy

Everything in Vilna is organized under workspaces:


```mermaid
flowchart TB
    W[Workspace] --> M[Members]
    W --> I[Invitations]
    W --> P[Projects]
    W --> RK[RPC Keys]
    W --> MK[Management Keys]
    P --> AK[API Keys]
    P --> PM[Project Members]
```

- 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.


## API key types

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.

Store keys securely
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.

## Invitation lifecycle

New team members join a workspace through email invitations. The flow:

1. An admin creates an invitation for an email address with a role (`admin` or `member`).
2. The invitee receives the invitation and can accept or decline.
3. On acceptance, the user becomes a workspace member with the assigned role.
4. 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 |


Admin protection
A workspace must retain at least one admin at all times. Removing the last admin or demoting them to `member` is rejected.

## Key rotation

To rotate an API key without downtime:

1. Create a new key with the same permissions.
2. Update your application to use the new key.
3. Verify the new key works in production.
4. Revoke the old key.


The same process applies to RPC keys and management keys.

## Common workflows

### Set up a new project

1. Create a project in your workspace (via dashboard or API).
2. Create an API key for the project with the permissions your application needs.
3. Use the API key in the `X-Api-Key` header to access the [Platform API](/apis/platform/).


### Onboard a team member

1. Send an invitation to the user's email.
2. Once accepted, assign the member to specific projects if their role is `member` (admins see all projects automatically).
3. The member can now access the workspace through the dashboard.


### Automate key provisioning

If your platform serves multiple customers, you can automate the setup for each one:

1. Create a project per customer.
2. Generate API keys programmatically for each project.
3. Distribute keys securely to each customer's integration.


This is the pattern used by exchanges, payment processors, and other platforms that manage multiple isolated environments. See the [API Reference](/apis/mgmt/api) for endpoint details.

## Next steps

Authorization
Roles, permissions, and the full permission matrix

API Reference
Complete endpoint documentation for all management operations

Quickstart
Integrate with the Platform API using your keys