{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/mgmt/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","cards","card"]},"type":"markdown"},"seo":{"title":"Management API Guide","projectTitle":"Vilna Docs","description":"Learn how workspaces, projects, team members, and API keys work together in Vilna. Resource hierarchy, key types, invitation lifecycle, and key rotation.","siteUrl":"https://docs.vilna.io","keywords":["crypto asset management","blockchain monitoring","digital asset security","cryptocurrency API","wallet tracking","blockchain analytics","enterprise crypto","real-time blockchain","CAIP-19","BIP44"],"lang":"en-US","image":"https://cdn.vilna.io/docs/previews/mgmt-api.png","meta":[{"name":"og:type","content":"website"},{"name":"og:site_name","content":"Vilna Documentation"},{"name":"og:image:width","content":"1200"},{"name":"og:image:height","content":"630"},{"name":"twitter:card","content":"summary_large_image"}],"llmstxt":{"title":"Vilna API Documentation","description":"Vilna is a blockchain monitoring and wallet management platform. It provides a single unified REST API for tracking addresses, transactions, balances, and activity across top blockchains - Bitcoin, Ethereum, Solana, TRON, TON, Cosmos, and others. The API uses CAIP-2/CAIP-19 standards for cross-chain identification, HD wallet management (BIP-32/44) for address derivation, and RFC 7807 for error responses. Authentication is via API key in the X-Api-Key header.\n","excludeFiles":["legal/**/*.md","@l10n/**/*.md"],"sections":[{"title":"Overview","description":"What Vilna is, supported blockchains, and target audience","includeFiles":["overview.md"],"excludeFiles":[]},{"title":"Getting Started","description":"Quickstart guide and core API concepts","includeFiles":["guides/quickstart.md","guides/dashboard.md","guides/core-concepts.md","guides/authentication.md"],"excludeFiles":[]},{"title":"API Reference","description":"Platform API and Management API endpoint documentation","includeFiles":["apis/platform/index.md","apis/mgmt/index.md","apis/rpc/index.md","apis/platform/api.yaml","apis/mgmt/api.yaml"],"excludeFiles":[]},{"title":"Developer Guides","description":"Integration patterns, events, notifications, SDK, and error handling","includeFiles":["guides/events.md","guides/channels.md","guides/integration-patterns.md","guides/sdk.md","guides/mcp.md","guides/errors.md","guides/simulation.md","guides/invoices.md"],"excludeFiles":[]},{"title":"Business","description":"Value proposition, use cases, and onboarding","includeFiles":["business/index.md","business/use-cases.md"],"excludeFiles":[]},{"title":"Optional","description":"Additional reference material","includeFiles":["guides/blockchain-basics.md","guides/faq.md","apis/mgmt/guide.md","guides/widget.md","guides/storage-client.md","apis/platform/caip-standards.md","apis/mgmt/authorization.md"],"excludeFiles":[]}],"hide":false},"priority":0.7,"jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"Management API","item":"https://docs.vilna.io/apis/mgmt"},{"@type":"ListItem","position":3,"name":"Guide"}]},{"@type":"TechArticle","headline":"Management API Guide","description":"Learn how workspaces, projects, team members, and API keys work together in Vilna.","url":"https://docs.vilna.io/apis/mgmt/guide","datePublished":"2026-01-15","proficiencyLevel":"Intermediate","image":"https://cdn.vilna.io/docs/previews/mgmt-api.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"management-api-guide","__idx":0},"children":["Management API Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains how workspaces, projects, team members, and API keys are organized in Vilna. For endpoint details, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/mgmt/api"},"children":["API Reference"]},". For roles and permissions, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/mgmt/authorization"},"children":["Authorization"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resource-hierarchy","__idx":1},"children":["Resource hierarchy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Everything in Vilna is organized under workspaces:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TB\n W[Workspace] --> M[Members]\n W --> I[Invitations]\n W --> P[Projects]\n W --> RK[RPC Keys]\n W --> MK[Management Keys]\n P --> AK[API Keys]\n P --> PM[Project Members]\n","diagramHtml":"

Workspace

Members

Invitations

Projects

RPC Keys

Management Keys

API Keys

Project Members

","diagramHtmlDark":"

Workspace

Members

Invitations

Projects

RPC Keys

Management Keys

API Keys

Project Members

"},"children":["flowchart TB\n W[Workspace] --> M[Members]\n W --> I[Invitations]\n W --> P[Projects]\n W --> RK[RPC Keys]\n W --> MK[Management Keys]\n P --> AK[API Keys]\n P --> PM[Project Members]\n"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["workspace"]}," is the top-level unit. Each user can create up to 5 workspaces."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Projects"]}," live inside a workspace and provide data isolation - each project has its own monitored addresses, transactions, and API keys."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Members"]}," are users with access to the workspace. They are added through invitations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API keys"]}," are scoped to a project. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["RPC keys"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["management keys"]}," are scoped to the workspace."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-key-types","__idx":2},"children":["API key types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna uses three types of API keys, each with a distinct prefix and scope:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Prefix"},"children":["Prefix"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scope"},"children":["Scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it accesses"},"children":["What it accesses"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vilna_api_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Project"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Platform API - addresses, transactions, balances, events, invoices"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["RPC key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vilna_rpc_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Workspace"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Blockchain RPC - JSON-RPC and gRPC node access"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Management key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vilna_mgt_"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Workspace"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Management API - workspaces, members, projects, keys"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Store keys securely"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"invitation-lifecycle","__idx":3},"children":["Invitation lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["New team members join a workspace through email invitations. The flow:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An admin creates an invitation for an email address with a role (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["admin"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The invitee receives the invitation and can accept or decline."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On acceptance, the user becomes a workspace member with the assigned role."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pending invitations can be revoked by any admin."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invitation sent, waiting for response"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["accepted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User accepted and became a member"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["declined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User declined the invitation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["revoked"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An admin cancelled the invitation"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Admin protection"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A workspace must retain at least one admin at all times. Removing the last admin or demoting them to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member"]}," is rejected."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-rotation","__idx":4},"children":["Key rotation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To rotate an API key without downtime:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a new key with the same permissions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update your application to use the new key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the new key works in production."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Revoke the old key."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same process applies to RPC keys and management keys."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-workflows","__idx":5},"children":["Common workflows"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"set-up-a-new-project","__idx":6},"children":["Set up a new project"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a project in your workspace (via dashboard or API)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create an API key for the project with the permissions your application needs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the API key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header to access the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/"},"children":["Platform API"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"onboard-a-team-member","__idx":7},"children":["Onboard a team member"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send an invitation to the user's email."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Once accepted, assign the member to specific projects if their role is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member"]}," (admins see all projects automatically)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The member can now access the workspace through the dashboard."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"automate-key-provisioning","__idx":8},"children":["Automate key provisioning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your platform serves multiple customers, you can automate the setup for each one:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a project per customer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate API keys programmatically for each project."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Distribute keys securely to each customer's integration."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the pattern used by exchanges, payment platforms, and other platforms that manage multiple isolated environments. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/mgmt/api"},"children":["API Reference"]}," for endpoint details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":9},"children":["Next steps"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Authorization","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/apis/mgmt/authorization"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Roles, permissions, and the full permission matrix"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"API Reference","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/apis/mgmt/api"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete endpoint documentation for all management operations"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Quickstart","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/quickstart"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integrate with the Platform API using your keys"]}]}]}]},"headings":[{"value":"Management API Guide","id":"management-api-guide","depth":1},{"value":"Resource hierarchy","id":"resource-hierarchy","depth":2},{"value":"API key types","id":"api-key-types","depth":2},{"value":"Invitation lifecycle","id":"invitation-lifecycle","depth":2},{"value":"Key rotation","id":"key-rotation","depth":2},{"value":"Common workflows","id":"common-workflows","depth":2},{"value":"Set up a new project","id":"set-up-a-new-project","depth":3},{"value":"Onboard a team member","id":"onboard-a-team-member","depth":3},{"value":"Automate key provisioning","id":"automate-key-provisioning","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Management API Guide","description":"Learn how workspaces, projects, team members, and API keys work together in Vilna. Resource hierarchy, key types, invitation lifecycle, and key rotation.","priority":0.7,"image":"https://cdn.vilna.io/docs/previews/mgmt-api.png","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"Management API","item":"https://docs.vilna.io/apis/mgmt"},{"@type":"ListItem","position":3,"name":"Guide"}]},{"@type":"TechArticle","headline":"Management API Guide","description":"Learn how workspaces, projects, team members, and API keys work together in Vilna.","url":"https://docs.vilna.io/apis/mgmt/guide","datePublished":"2026-01-15","proficiencyLevel":"Intermediate","image":"https://cdn.vilna.io/docs/previews/mgmt-api.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-05-26T20:25:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/mgmt/guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}