How to Manage Virtual Keys

Last update:
3/9/2026 · 5 min read

---

IN THIS ARTICLE

This guide covers registering, using, and managing virtual keys. If you are setting up MCP for the first time, see MCP Quickstart: How to Connect Your AI Agent for a step-by-step guide.

What is a virtual key?

A virtual key is a short, revocable token mcp_vk_... you use instead of your real Albato API token when configuring your MCP client.

Why it matters

Your real Albato token may be long-lived and used elsewhere beyond this integration. A virtual key lets you issue a separate, narrowly-scoped credential per agent or integration. If one MCP client config leaks (for example, committed to a repo by mistake, or a laptop is compromised), you revoke just that virtual key in one API call, without touching your real Albato token or any other agent's access.

Prerequisites

Before you register a virtual key, make sure you have a Registration Secret (reg_...) from your Albato manager. Each company gets just one, so keep it safe: whoever holds it can create new virtual keys for your contract.

How to register a virtual key

curl -X POST <MCP_SERVER_URL>/auth/register \
-H "Authorization: Bearer YOUR_REGISTRATION_SECRET" \
-H "Content-Type: application/json" \
-d '{
"albatoToken": "YOUR_ALBATO_TOKEN",
"label": "my-agent",
"expiresAt": "2026-12-31T23:59:59Z"
}'

Response

{
"virtualKey": "mcp_vk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"contractId": "acme",
"expiresAt": "2026-12-31T23:59:59.000Z",
"createdAt": "2026-07-09T10:00:00.000Z"
}

Save the virtualKey value. It is shown only once and not stored on the server.

How to use your virtual key in your MCP client

Claude Desktop / MCP client config

{
"mcpServers": {
"albato": {
"url": "<MCP_SERVER_URL>/mcp",
"headers": {
"Authorization": "Bearer mcp_vk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}

Direct API call

curl <MCP_SERVER_URL>/mcp/tools \
-H "Authorization: Bearer mcp_vk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

See the MCP Quickstart for the full connection walkthrough, and the MCP Tools Reference for what your agent can do once connected.

How to manage your keys

How to list your keys

curl <MCP_SERVER_URL>/client/keys \
-H "Authorization: Bearer YOUR_REGISTRATION_SECRET"

{
"contractId": "acme",
"keys": [
{
"keyHint": "...9d3f",
"label": "sales-agent",
"expiresAt": "2026-12-31T23:59:59.000Z",
"createdAt": "2026-07-09T10:00:00.000Z"
}
],
"total": 1
}

keyHint is the last 4 characters of the virtual key, for identification only.

How to refresh a key

Your Albato token behind a virtual key expires periodically (see the note above). When it does, fetch a fresh Albato token via the Embedded API using your master token, then update the existing virtual key in place. There's no need to touch your agent's config: the mcp_vk_... value doesn't change.

curl -X POST <MCP_SERVER_URL>/client/keys/refresh \
-H "Authorization: Bearer YOUR_REGISTRATION_SECRET" \
-H "Content-Type: application/json" \
-d '{"virtualKey": "mcp_vk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "albatoToken": "FRESH_ALBATO_TOKEN"}'

{ "refreshed": true, "contractId": "acme", "label": "sales-agent" }

If a request through your agent starts returning 401 with a hint about an expired Albato token, this is the fix. Best to automate it on a schedule (for example, daily) rather than waiting for it to break first.

How to revoke a key

curl -X POST <MCP_SERVER_URL>/client/keys/revoke \
-H "Authorization: Bearer YOUR_REGISTRATION_SECRET" \
-H "Content-Type: application/json" \
-d '{"virtualKey": "mcp_vk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'

The effect is immediate: any subsequent request using the revoked key returns 401.

Recommended practices

• One key per agent. Create a separate virtual key for each agent or integration. If one is compromised, revoke only that key without affecting others.
• Use labels. Always set a label so you can identify keys in the list ("crm-agent", "slack-bot", "onboarding-flow").
• Set expiry for temporary access. Pass expiresAt for trials or time-limited integrations. Expired keys are rejected automatically.
• Revoke on personnel changes. If a developer who had access to virtual keys leaves, revoke their keys immediately. Your Albato token is unaffected.
• Automate refresh. Your Albato session token expires periodically (often around a week). Run a scheduled job that fetches a fresh token from the Embedded API and calls /client/keys/refresh for each of your virtual keys, instead of waiting for a 401 and re-registering.

Error reference

Need help? Contact your Albato manager or reach out to the Albato technical team.