For authenticated calls, send your key in the 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.
X-Api-Key header Four key types Scoped, least-privilege Revoke & rotate anytime
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 X-Api-Key header, with a fixed set of permissions chosen at creation. Pick a key to see the specifics:
Platform API - blockchain data and operations for one project.
| Field | Value |
|---|---|
| Prefix | vilna_api_ |
| Scope | A single project |
| Endpoint | https://api.vilna.io/v2 |
| Header | X-Api-Key |
Use it for addresses, transactions, balances, events and invoices. Created on the project's API keys page.
For request examples and the request builder, open List blockchains.
Direct blockchain node access across every chain.
| Field | Value |
|---|---|
| Prefix | vilna_rpc_ |
| Scope | The whole workspace |
| HTTP | https://rpc.vilna.io · header X-Api-Key |
| gRPC | grpc.vilna.io:443 · metadata x-api-key |
One key reaches every supported chain - pick the chain in the request path (or gRPC metadata). Created in workspace settings.
export VILNA_RPC_KEY="<rpc-key>"
curl "https://rpc.vilna.io/ethereum" \
-H "X-Api-Key: $VILNA_RPC_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'The chains list needs no key: GET https://rpc.vilna.io/chains.
Administer workspaces, projects, members and keys.
| Field | Value |
|---|---|
| Prefix | vilna_mgt_ |
| Scope | The whole workspace |
| Endpoint | https://mgmt.vilna.io/v1 |
| Header | X-Api-Key |
Use it for Management API operations within its workspace and granted permissions, including API/RPC key administration. Create the workspace and management key in the dashboard. See Permissions for actions that require a user session.
For request examples and the request builder, open List workspace projects.
Coordinate signer approvals and transaction signing.
| Field | Value |
|---|---|
| Prefix | vilna_vks_ |
| Scope | The whole workspace |
| Endpoint | https://vks.vilna.io/v1 |
| Header | X-Api-Key |
| Permission | vks:access for every published operation |
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 VKS in the Dashboard.
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.
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 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 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.
Pass the key in the 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.
Open the operation page and enter the key in its authorization form. For example, List blockchains provides request examples in multiple languages.
A key never carries blanket access. At creation you grant it a fixed set of permissions - strings like api:address:read - and any call outside that set is rejected with 403. Permissions can't be widened afterwards; to change them, revoke the key and issue a new one.
The permission model, the full per-service catalogue, and how roles map to it live in the Permissions reference.
Authentication failures use application/problem+json:
| Status | Means | Fix |
|---|---|---|
401 | The key is missing, malformed or revoked | Send a valid key in X-Api-Key |
403 | The key is valid but lacks the required permission | Issue a replacement with the required permissions |
Never ship a key in a browser or mobile app. Payers use the unauthenticated public invoice page instead.
An address inventory reader needs api:address:read, not every scope. Scope each key to the one job it does.
Separate development, staging and production so revoking one never touches the others.
When someone with key access leaves, rotate - issue a new key, switch traffic, revoke the old one.
Rotate any key - API, RPC or management - with zero downtime:
- Create a new key with the same permissions.
- Switch your application to the new key.
- Confirm the new key works in production.
- Revoke the old key.
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 Webhooks reference.