{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["quickfacts","fact","tilegrid","tile","intent","intentcell","admonition","eventexplorer","eventkind","cap"]},"type":"markdown"},"seo":{"title":"Permissions & scopes","projectTitle":"Vilna Docs","description":"How Vilna API permissions work - the colon-separated permission string, its shape per service, the full catalog, and how roles and keys carry it.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/apis-permissions.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"},{"name":"robots","content":"max-image-preview:large"}],"llmstxt":{"title":"Vilna API Documentation","description":"Vilna Platform API monitors public blockchain activity, balances and invoices and delivers signed webhooks. It does not sign or broadcast transactions. VKS separately coordinates account setup, signer approvals and signing, retains signed results and can submit a complete transaction to a node. Node acceptance is not blockchain confirmation. Each API uses its own scoped credential in X-Api-Key. Workspace setup and VKS-key issuance start in the Dashboard.\n","details":{"content":"**Platform monitoring.** Platform observes merchant-controlled addresses,\nsupplied directly or derived from the merchant's extended public key (xPub).\nInvoices report incoming on-chain activity; they do not initiate transfers.\n\n**APIs and their credentials.**\n\n- Platform API (api.vilna.io) - monitor addresses and extended public keys, read\n  balances and transactions, reconcile incoming payments, create invoices, and\n  receive events.\n- Blockchain RPC (rpc.vilna.io) - JSON-RPC and gRPC node access across every\n  supported network behind one key.\n- Management API (mgmt.vilna.io) - published workspace, project, member and key\n  operations, with Dashboard bootstrap and credential grant limits.\n- VKS API (vks.vilna.io) - workspace signers, vaults, accounts, signing requests,\n  signed results and optional asynchronous send. Uses a Dashboard-issued VKS key\n  with vks:access; the public Management API has no VKS-key issuance route.\n\n**Pages with no markdown source**, so they cannot be linked below:\n\n- Product overview: https://docs.vilna.io/\n- All guides: https://docs.vilna.io/guides\n"},"excludeFiles":["legal/terms.md","legal/privacy.md","legal/cookies.md","@l10n/ru/legal/terms.md","@l10n/ru/legal/privacy.md","@l10n/ru/legal/cookies.md"],"sections":[{"title":"Getting Started","description":"What the platform is, how to make a first call, and answers to common questions","includeFiles":["get-started/quickstart.md","get-started/dashboard.md","get-started/core-concepts.md","get-started/members.md","get-started/faq.md"]},{"title":"API Reference","description":"Authentication, permissions, idempotency, errors, standards, and per-service endpoint documentation","includeFiles":["apis/authentication.md","apis/permissions.md","apis/idempotency.md","apis/errors.md","apis/standards.md","apis/networks.md","apis/platform/@v2/index.md","apis/platform/@v2/webhooks.md","apis/platform/@v2/api.yaml","apis/mgmt/index.md","apis/mgmt/api.yaml","apis/vks/index.md","apis/vks/api.yaml","apis/rpc/index.md","apis/rpc/json-rpc.md","apis/rpc/grpc.md"]},{"title":"Developer Guides","description":"Integration patterns, events, notifications, and tooling","includeFiles":["guides/events.md","guides/channels.md","guides/tokens.md","guides/integration-patterns.md","guides/mcp.md","guides/simulation.md","guides/invoices.md","guides/vks.md"]},{"title":"Trust and custody","description":"The non-custodial model in plain terms","includeFiles":["legal/non-custodial.md"]},{"title":"Optional","description":"Background reading and release history","includeFiles":["get-started/blockchain-basics.md","changelog.md"]}]},"priority":0.6,"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":"API Reference","item":"https://docs.vilna.io/apis"},{"@type":"ListItem","position":3,"name":"Permissions"}]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"permissions","__idx":0},"children":["Permissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Permissions decide what an API key or a teammate can do. Every permission is a colon-separated string like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:address:read"]},", read left to right - and how many segments it has depends on which service it belongs to. This page is the access model itself; for who sits in which seat on your team, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/members"},"children":["Members & roles"]},"."]},{"$$mdtype":"Tag","name":"QuickFacts","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"layers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vks"]}]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"check-double"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write"]}," · ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete"]}]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"search"},"children":["Exact-match checks"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"lock"},"children":["Fixed at creation"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"model","level":2,"__idx":1},"children":["The permission model "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A permission is a colon-separated string, read left to right: the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["scope"]}," (the service - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt"]},"), the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["resource"]}," (the object it covers, like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member"]},"), and the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["action"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["write"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Platform API uses all three. RPC exposes a single capability, so it drops the resource; the Management API inserts a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["level"]}," segment - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["workspace"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["project"]}," - before the resource, giving it four parts:"]},{"$$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":"Service"},"children":["Service"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format"},"children":["Format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Platform API"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:{resource}:{action}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:address:read"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Blockchain RPC"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc:{action}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc:call"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Management API"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:{level}:{resource}:{action}"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:workspace:member:write"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Checks are exact string match - a permission grants only the action it names, with no implied hierarchy. A key with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:address:read"]}," can list and read addresses, but registering one needs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:address:write"]},". Grant every action you actually use."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"actions","level":2,"__idx":2},"children":["The three actions "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three verbs cover almost every resource, and they mean the same thing in every scope:"]},{"$$mdtype":"Tag","name":"TileGrid","attributes":{"cols":"3"},"children":[{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"search","title":"read"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lists and views objects. Read-only - never changes state."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"zap","title":"write"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creates new objects and updates existing ones."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"alert","title":"delete"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Permanently removes objects. Not every resource supports it."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two operations use a fourth action, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]},", instead: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc:call"]}," sends a node request, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:simulate:call"]}," runs a transaction simulation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"attach","level":2,"__idx":3},"children":["How permissions attach "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Permissions never float free - something carries them. A key and a member each get their set a different way:"]},{"$$mdtype":"Tag","name":"Intent","attributes":{},"children":[{"$$mdtype":"Tag","name":"IntentCell","attributes":{"label":"Keys","icon":"lock"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Carry a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["fixed set"]}," chosen at creation. An API key gets the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api"]}," permissions you pick (scoped to one project); an RPC key gets ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc:call"]},"; a management key gets a safe subset of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt"]}," permissions."]}]},{"$$mdtype":"Tag","name":"IntentCell","attributes":{"label":"Members","icon":"users"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A member's ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/members"},"children":["role"]}," supplies default permissions. Authorized users can separately manage the member's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vks:access"]}," grant through a dashboard session."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Keys are fixed at creation"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no endpoint to widen or narrow a key after it exists. To change what a key can do, revoke it and create a new one with the permissions you want."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"services","level":2,"__idx":4},"children":["Permissions by service "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pick a scope to see every permission it defines. The scope - the first segment of the string - is also the service the permission belongs to."]},{"$$mdtype":"Tag","name":"EventExplorer","attributes":{},"children":[{"$$mdtype":"Tag","name":"EventKind","attributes":{"name":"api","desc":"Platform API - blockchain operations on a project.","chains":"Project-scoped, vilna_api_"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:{resource}:{action}"]},". Each resource supports a different mix of actions:"]},{"$$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":"resource"},"children":["resource"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"read"},"children":["read"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"write"},"children":["write"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"delete"},"children":["delete"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limits"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activity"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blockchain"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["balance"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["public_key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_tag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address_tag"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One more sits outside the grid: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:simulate:call"]}," runs a transaction simulation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:activity:read"]}," authorizes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v2/activity"]},". Transaction list and detail operations require ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:transaction:read"]},". Grant both permissions if your integration reads activity and transactions."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"name":"mgt","desc":"Management API - workspace and project administration.","chains":"Workspace-scoped, vilna_mgt_"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:{level}:{resource}:{action}"]},". Permissions split into a workspace level and a project level - read each cell as the full four-segment string."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workspace level"]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:workspace:{resource}:{action}"]}]},{"$$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":"resource"},"children":["resource"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"read"},"children":["read"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"write"},"children":["write"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"delete"},"children":["delete"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["self"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["project"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc_key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:workspace:member:*"]}," also covers assigning, updating and removing a project's members - there is no separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:project:member:*"]}," string."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Project level"]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:project:{resource}:{action}"]}]},{"$$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":"resource"},"children":["resource"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"read"},"children":["read"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"write"},"children":["write"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"center","data-label":"delete"},"children":["delete"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["self"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":[{"$$mdtype":"Tag","name":"Cap","attributes":{"on":true},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"center"},"children":["-"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:project:self:delete"]}," deletes the project itself; nothing else uses the project-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["self"]}," resource."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"name":"rpc","desc":"Blockchain RPC - direct node access across every chain.","chains":"Workspace-scoped, vilna_rpc_"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc:{action}"]}," - no resource segment."]},{"$$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":"Permission"},"children":["Permission"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Grants"},"children":["Grants"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rpc:call"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send JSON-RPC and gRPC requests to any supported chain"]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"management-key-limits","level":2,"__idx":5},"children":["Management-key limits "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A management key can list and read API/RPC key metadata with the corresponding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read"]}," permission. Creating and revoking API keys requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:project:api_key:write"]},"; creating and revoking RPC keys requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:workspace:rpc_key:write"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following actions require a user session in the dashboard and the appropriate workspace role:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Management keys"]}," - listing, viewing, creating and revoking. Neither ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:workspace:mgt_key:read"]}," nor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt:workspace:mgt_key:write"]}," can be granted to a management key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["VKS keys"]}," - listing, viewing, creating and revoking; available to workspace owners and admins."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Workspace deletion or transfer"]}," - available only to the workspace owner."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Previously granted access to Management keys may still appear in saved key details. Those permissions no longer authorize these operations and cannot be selected when issuing a new key."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"roles","level":2,"__idx":6},"children":["Roles & permissions "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Roles supply the default permission sets below. A workspace role grants ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt"]}," permissions; a project role grants ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api"]}," permissions. Workspace Owners and Admins have VKS access automatically. A Member needs an explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vks:access"]}," grant through the dashboard; this does not change their project role or any API key's permissions."]},{"$$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":"Role"},"children":["Role"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Level"},"children":["Level"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Permission set"},"children":["Permission set"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Owner"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Workspace"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Everything an Admin has, plus deleting or transferring the workspace. One owner per workspace, set at creation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Admin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Workspace"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mgt"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api"]}," - manage members, projects, and keys, but not delete or transfer the workspace."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Member"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Workspace"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read-only at the workspace level; reaches only the projects they are assigned."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Editor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Project"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api"]}," read, write, and delete on that project's resources."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Viewer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Project"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read project resources and simulate transactions (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:simulate:call"]},")."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A workspace Owner or Admin manages every project automatically; a Member needs an Editor or Viewer seat on each project to reach it. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/members"},"children":["Members & roles"]}," for the seat descriptions and how to invite or change someone."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"denied","level":2,"__idx":7},"children":["When access is denied "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A valid key without the required permission receives ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/errors#forbidden"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 Forbidden"]}]},". Check the operation’s required grant and the key’s permissions. To change a key’s grants, issue a replacement and revoke the old key."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"vks","level":2,"__idx":8},"children":["VKS "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every published VKS operation requires ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vks:access"]}," on a workspace VKS key, including reads, creation, deletion and send. This is access to the public VKS API as a whole, without separate read/write grants. Issue the key in the Dashboard; Dashboard role grants do not establish a public Management key-issuance operation. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/vks"},"children":["VKS"]},"."]}]},"headings":[{"value":"Permissions","id":"permissions","depth":1},{"value":"The permission model","id":"model","depth":2},{"value":"The three actions","id":"actions","depth":2},{"value":"How permissions attach","id":"attach","depth":2},{"value":"Permissions by service","id":"services","depth":2},{"value":"Management-key limits","id":"management-key-limits","depth":2},{"value":"Roles & permissions","id":"roles","depth":2},{"value":"When access is denied","id":"denied","depth":2},{"value":"VKS","id":"vks","depth":2}],"frontmatter":{"seo":{"title":"Permissions & scopes","description":"How Vilna API permissions work - the colon-separated permission string, its shape per service, the full catalog, and how roles and keys carry it.","priority":0.6,"image":"https://cdn.vilna.io/docs/og/26103121/en/apis-permissions.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":"API Reference","item":"https://docs.vilna.io/apis"},{"@type":"ListItem","position":3,"name":"Permissions"}]}]}}},"lastModified":"2026-11-05T09:40:36.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/permissions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}