{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["quickfacts","fact","eventexplorer","eventkind","admonition","tilegrid","tile"]},"type":"markdown"},"seo":{"title":"Authentication - API keys","projectTitle":"Vilna Docs","description":"How to authenticate with the Vilna API using API keys, the key types per service, and credential security best practices.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/apis-authentication.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.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":"API Reference","item":"https://docs.vilna.io/apis"},{"@type":"ListItem","position":3,"name":"Authentication"}]},{"@type":"TechArticle","headline":"Authentication - API keys","description":"How to authenticate with the Vilna API using API keys, the key types per service, and credential security best practices.","url":"https://docs.vilna.io/apis/authentication","datePublished":"2025-09-17","dateModified":"2026-11-01","proficiencyLevel":"Beginner","dependencies":"Vilna account","image":"https://cdn.vilna.io/docs/og/26103121/en/apis-authentication.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":"authentication","__idx":0},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For authenticated calls, send your key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header. Choose the key type and permissions for the API you use; public operations marked in the reference do not need a key."]},{"$$mdtype":"Tag","name":"QuickFacts","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"lock"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"layers"},"children":["Four key types"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"shield-check"},"children":["Scoped, least-privilege"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"zap"},"children":["Revoke & rotate anytime"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"keys","level":2,"__idx":1},"children":["Keys by service "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each service has its own key type, scoped to either a single project or the whole workspace. They all authenticate the same way - sent in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header, with a fixed set of permissions chosen at creation. Pick a key to see the specifics:"]},{"$$mdtype":"Tag","name":"EventExplorer","attributes":{},"children":[{"$$mdtype":"Tag","name":"EventKind","attributes":{"name":"API key","desc":"Platform API - blockchain data and operations for one project.","chains":"vilna_api_, Project-scoped"},"children":[{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prefix"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vilna_api_"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A single project"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.vilna.io/v2"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Header"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use it for addresses, transactions, balances, events and invoices. Created on the project's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API keys"]}," page."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For request examples and the request builder, open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/blockchain/list-blockchains"},"children":["List blockchains"]},"."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"name":"RPC key","desc":"Direct blockchain node access across every chain.","chains":"vilna_rpc_, Workspace-scoped"},"children":[{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prefix"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vilna_rpc_"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The whole workspace"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://rpc.vilna.io"]}," · header ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["gRPC"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grpc.vilna.io:443"]}," · metadata ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One key reaches every supported chain - pick the chain in the request path (or gRPC metadata). Created in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["workspace settings"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"export VILNA_RPC_KEY=\"<rpc-key>\"\ncurl \"https://rpc.vilna.io/ethereum\" \\\n  -H \"X-Api-Key: $VILNA_RPC_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The chains list needs no key: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET https://rpc.vilna.io/chains"]},"."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"name":"Management key","desc":"Administer workspaces, projects, members and keys.","chains":"vilna_mgt_, Workspace-scoped"},"children":[{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prefix"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vilna_mgt_"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The whole workspace"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://mgmt.vilna.io/v1"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Header"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use it for ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/mgmt/api"},"children":["Management API operations"]}," within its workspace and granted permissions, including API/RPC key administration. Create the workspace and management key in the dashboard. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/permissions#management-key-limits"},"children":["Permissions"]}," for actions that require a user session."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For request examples and the request builder, open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/mgmt/api/project/list-workspace-projects"},"children":["List workspace projects"]},"."]}]},{"$$mdtype":"Tag","name":"EventKind","attributes":{"id":"vks","name":"VKS key","desc":"Coordinate signer approvals and transaction signing.","chains":"vilna_vks_, Workspace-scoped"},"children":[{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prefix"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vilna_vks_"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The whole workspace"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://vks.vilna.io/v1"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Header"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Permission"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vks:access"]}," for every published operation"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Issue the key in the Dashboard. Platform, RPC and management keys do not replace it; the public Management API has no VKS-key issuance operation. Working with VKS through the website uses your user session and does not require this key. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/vks"},"children":["VKS in the Dashboard"]},"."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"format","level":2,"__idx":2},"children":["Handling a key "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat the key as an opaque secret. Its prefix identifies its purpose; send the complete value unchanged. Do not derive or validate its contents yourself."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Store the secret immediately"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the key from the creation response in a secrets manager. The key-creation contracts allow an authorized caller to retry the same request with its original ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," to recover the secret for 60 seconds from successful creation, subject to current access and key state. Retries do not extend the window or restore a revoked or deleted key. Later reads return only a mask and metadata. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/idempotency#replay"},"children":["Idempotency"]}," for replay windows and limits. After expiry, find the created key and revoke it if needed; issue a replacement only as a deliberate new intent."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"request","level":2,"__idx":3},"children":["Send the key "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass the key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header on every authenticated request - never in the query string or URL path, where it leaks into logs, proxies and browser history."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open the operation page and enter the key in its authorization form. For example, ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/blockchain/list-blockchains"},"children":["List blockchains"]}," provides request examples in multiple languages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"scopes","level":2,"__idx":4},"children":["Scopes & permissions "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A key never carries blanket access. At creation you grant it a fixed set of permissions - strings like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:address:read"]}," - and any call outside that set is rejected with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},". Permissions can't be widened afterwards; to change them, revoke the key and issue a new one."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The permission model, the full per-service catalogue, and how roles map to it live in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/permissions"},"children":["Permissions reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"errors","level":2,"__idx":5},"children":["When auth fails "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication failures use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/problem+json"]},":"]},{"$$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":"Means"},"children":["Means"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/errors#unauthorized"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key is missing, malformed or revoked"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send a valid key in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/errors#forbidden"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The key is valid but lacks the required permission"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issue a replacement with the required ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/permissions"},"children":["permissions"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"practices","level":2,"__idx":6},"children":["Best practices "]},{"$$mdtype":"Tag","name":"TileGrid","attributes":{"cols":"2"},"children":[{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"shield","title":"Keys are server-side only"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never ship a key in a browser or mobile app. Payers use the unauthenticated public invoice page instead."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"lock","title":"Grant least privilege"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An address inventory reader needs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:address:read"]},", not every scope. Scope each key to the one job it does."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"layers","title":"One key per environment"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Separate development, staging and production so revoking one never touches the others."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"zap","title":"Rotate on staff changes"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When someone with key access leaves, rotate - issue a new key, switch traffic, revoke the old one."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"rotation","level":2,"__idx":7},"children":["Rotating a key "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rotate any key - API, RPC or management - with zero 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":["Switch your application to the new key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm the new key works in production."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Revoke the old key."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"webhooks","level":2,"__idx":8},"children":["Webhook signatures "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook deliveries are signed with HMAC-SHA256 so you can confirm they came from Vilna. The signature headers, the signing-secret lifecycle, and the verification code are documented in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/webhooks#verify"},"children":["Webhooks reference"]},"."]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"Keys by service","id":"keys","depth":2},{"value":"Handling a key","id":"format","depth":2},{"value":"Send the key","id":"request","depth":2},{"value":"Scopes & permissions","id":"scopes","depth":2},{"value":"When auth fails","id":"errors","depth":2},{"value":"Best practices","id":"practices","depth":2},{"value":"Rotating a key","id":"rotation","depth":2},{"value":"Webhook signatures","id":"webhooks","depth":2}],"frontmatter":{"seo":{"title":"Authentication - API keys","description":"How to authenticate with the Vilna API using API keys, the key types per service, and credential security best practices.","priority":0.7,"image":"https://cdn.vilna.io/docs/og/26103121/en/apis-authentication.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":"Authentication"}]},{"@type":"TechArticle","headline":"Authentication - API keys","description":"How to authenticate with the Vilna API using API keys, the key types per service, and credential security best practices.","url":"https://docs.vilna.io/apis/authentication","datePublished":"2025-09-17","dateModified":"2026-11-01","proficiencyLevel":"Beginner","dependencies":"Vilna account","image":"https://cdn.vilna.io/docs/og/26103121/en/apis-authentication.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-10-31T22:45:00.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}