# Management API

Vilna Management API. Manage workspaces, projects, team members, and API keys.

**Authentication**

Every request must include a management key (`vilna_mgt_...`) in the `X-Api-Key` header. Management keys are workspace-scoped: each key only sees the workspace it was created in. Every operation lists the permission scopes its key must hold (e.g., `mgt:project:write`). A key missing the required scope gets `403 Forbidden`.

**Key Types**

Vilna has three key types, each with its own prefix. Don't mix them:

- `vilna_mgt_...`: management keys authenticate calls to this API (manage workspaces, projects, members, and other keys).
- `vilna_api_...`: project-scoped API keys for the public Vilna API (`api.vilna.io`).
- `vilna_rpc_...`: workspace-scoped keys for blockchain JSON-RPC endpoints (`rpc.vilna.io`).

This API creates and revokes API keys and RPC keys. Management keys are issued via the Vilna dashboard and can't be listed or rotated here. Their lifecycle events (`mgt_key.created`, `mgt_key.revoked`) still appear in the activity log so admins can audit changes.

**Quick Links**

- [Authorization Guide](/apis/mgmt/authorization) - Roles, permissions, and access control
- [Quick Start Guide](/guides/quickstart) - Step-by-step integration tutorial

**Endpoints**

Workspace Management

- **[Members](#tag/member)** - Workspace members and their roles
- **[Invitations](#tag/invitation)** - Workspace invitation lifecycle
- **[Projects](#tag/project)** - Create, update, and delete projects within a workspace
- **[Project Members](#tag/project_member)** - Assign and manage project-level member access
- **[Activity Log](#tag/log)** - Audit trail of workspace activity

Key Management

- **[API Keys](#tag/api_key)** - Project-scoped API keys for the public Vilna API
- **[RPC Keys](#tag/rpc_key)** - Workspace-scoped keys for blockchain RPC endpoints

RPC Access

- **[RPC](#tag/rpc)** - Workspace RPC endpoint details

Infrastructure

- **[Version](#tag/version)** - Service version info

**Need Help?**

Visit our [documentation portal](/apis/mgmt/authorization) for detailed guides and examples.


Version: 0.23.9
License: Apache 2.0

## Servers

Vilna Management API.
```
https://mgmt.vilna.io/v1
```

## Security

### Auth

Management key (`vilna_mgt_...`). Send it in the `X-Api-Key` header on every request. The key must hold all scopes listed on the operation; a missing scope yields `403 Forbidden`. API keys (`vilna_api_...`) and RPC keys (`vilna_rpc_...`) are not accepted here; they authenticate the public API and RPC gateways respectively.


Type: apiKey
In: header
Name: X-Api-Key

## Download OpenAPI description

[Management API](https://docs.vilna.io/_bundle/@l10n/ru/apis/mgmt/api.yaml)

## Members

Workspace members and their roles (`admin`, `member`).

### List workspace members

 - [GET /workspaces/{workspace_id}/members](https://docs.vilna.io/ru/apis/mgmt/api/member/list-workspace-members.md): Return workspace members with their roles.

### Update workspace member

 - [PATCH /workspaces/{workspace_id}/members/{user_id}](https://docs.vilna.io/ru/apis/mgmt/api/member/patch-workspace-member.md): Update a member's workspace role. Demoting the last admin is rejected with 409 Conflict.

### Remove workspace member

 - [DELETE /workspaces/{workspace_id}/members/{user_id}](https://docs.vilna.io/ru/apis/mgmt/api/member/remove-workspace-member.md): Remove a member from the workspace and revoke all of their project grants. Removing the last admin is rejected with 409 Conflict.

## Invitations

Workspace invitation lifecycle (`pending`, `accepted`, `declined`, `revoked`, `expired`).

### List workspace invitations

 - [GET /workspaces/{workspace_id}/invitations](https://docs.vilna.io/ru/apis/mgmt/api/invitation/list-workspace-invitations.md): Return workspace invitations in any lifecycle status.

### Create workspace invitation

 - [POST /workspaces/{workspace_id}/invitations](https://docs.vilna.io/ru/apis/mgmt/api/invitation/create-workspace-invitation.md): Create an invitation by email with an optional bundle of project grants. Idempotent: returns 200 OK if a pending invitation for the same recipient already exists.

### Revoke workspace invitation

 - [POST /workspaces/{workspace_id}/invitations/{invitation_id}/actions/revoke](https://docs.vilna.io/ru/apis/mgmt/api/invitation/revoke-workspace-invitation.md): Revoke a pending invitation. Invitations in terminal status cannot be revoked.

## Activity Log

Audit trail of member, project, and key activity within a workspace.

### List activity log

 - [GET /workspaces/{workspace_id}/logs](https://docs.vilna.io/ru/apis/mgmt/api/log/list-workspace-logs.md): Return workspace activity events in reverse-chronological order.

## Projects

Create, update, and delete projects within a workspace.

### List workspace projects

 - [GET /workspaces/{workspace_id}/projects](https://docs.vilna.io/ru/apis/mgmt/api/project/list-workspace-projects.md): Return projects within a workspace. Workspace admins receive all projects; members receive only projects where they hold an explicit grant.

### Create project

 - [POST /workspaces/{workspace_id}/projects](https://docs.vilna.io/ru/apis/mgmt/api/project/create-workspace-project.md): Create a new project in the workspace.

### Get project

 - [GET /projects/{project_id}](https://docs.vilna.io/ru/apis/mgmt/api/project/get-project.md): Return a project by ID.

### Update project

 - [PATCH /projects/{project_id}](https://docs.vilna.io/ru/apis/mgmt/api/project/patch-project.md): Update a project's name.

### Delete project

 - [DELETE /projects/{project_id}](https://docs.vilna.io/ru/apis/mgmt/api/project/delete-project.md): Soft-delete a project. Nested keys and member grants are purged asynchronously.

## Project Members

Project-level grants for workspace members (`editor`, `viewer`).

### List project members

 - [GET /projects/{project_id}/members](https://docs.vilna.io/ru/apis/mgmt/api/project_member/list-project-members.md): Return explicit project grants (editors and viewers). Workspace admins have implicit access and are not listed.

### Assign project member

 - [POST /projects/{project_id}/members](https://docs.vilna.io/ru/apis/mgmt/api/project_member/assign-project-member.md): Grant a workspace member project-level access (editor or viewer). Idempotent: returns 200 OK if the grant already exists with the same role, 409 Conflict if it exists with a different role.

### Update project member

 - [PATCH /projects/{project_id}/members/{user_id}](https://docs.vilna.io/ru/apis/mgmt/api/project_member/patch-project-member.md): Update a member's project role.

### Remove project member

 - [DELETE /projects/{project_id}/members/{user_id}](https://docs.vilna.io/ru/apis/mgmt/api/project_member/remove-project-member.md): Remove a project grant. The member remains in the workspace.

## RPC

Workspace-scoped access to blockchain JSON-RPC nodes.

### Get workspace RPC

 - [GET /workspaces/{workspace_id}/rpc](https://docs.vilna.io/ru/apis/mgmt/api/rpc/get-workspace-rpc.md): Return the workspace RPC singleton configuration. Provisioned automatically with every workspace and always available to its members.

## API Keys

Manage project-scoped API keys (`vilna_api_...`) used to authenticate the public Vilna API (`api.vilna.io`). A project must exist before a key can be created. The raw secret is returned only in the create response.


### List project keys

 - [GET /projects/{project_id}/keys](https://docs.vilna.io/ru/apis/mgmt/api/api_key/list-project-keys.md): Return project API keys.

### Create project key

 - [POST /projects/{project_id}/keys](https://docs.vilna.io/ru/apis/mgmt/api/api_key/create-project-key.md): Create a new project API key. The raw secret is returned once and cannot be retrieved again.

### Get project key

 - [GET /projects/{project_id}/keys/{key_id}](https://docs.vilna.io/ru/apis/mgmt/api/api_key/get-project-key.md): Return a project API key by ID.

### Revoke project key

 - [POST /projects/{project_id}/keys/{key_id}/actions/revoke](https://docs.vilna.io/ru/apis/mgmt/api/api_key/revoke-project-key.md): Revoke a project API key. Once revoked, the key can no longer be used for authentication.

## RPC Keys

Manage workspace-scoped RPC keys (`vilna_rpc_...`) used to authenticate the blockchain JSON-RPC gateway (`rpc.vilna.io`). The raw secret is returned only in the create response.


### List RPC keys

 - [GET /workspaces/{workspace_id}/rpc/keys](https://docs.vilna.io/ru/apis/mgmt/api/rpc_key/list-workspace-rpc-keys.md): Return workspace RPC keys.

### Create RPC key

 - [POST /workspaces/{workspace_id}/rpc/keys](https://docs.vilna.io/ru/apis/mgmt/api/rpc_key/create-workspace-rpc-key.md): Create a new workspace RPC key. The raw secret is returned once and cannot be retrieved again.

### Get RPC key

 - [GET /workspaces/{workspace_id}/rpc/keys/{key_id}](https://docs.vilna.io/ru/apis/mgmt/api/rpc_key/get-workspace-rpc-key.md): Return a workspace RPC key by ID.

### Revoke RPC key

 - [POST /workspaces/{workspace_id}/rpc/keys/{key_id}/actions/revoke](https://docs.vilna.io/ru/apis/mgmt/api/rpc_key/revoke-workspace-rpc-key.md): Revoke a workspace RPC key. Once revoked, the key can no longer be used for authentication.

## Version

Service version information.

### Get service version

 - [GET /version](https://docs.vilna.io/ru/apis/mgmt/api/version/get-version.md): Return the current API version.