# How to Manage Virtual Keys | Albato MCP Source: https://albato.com/wiki/articles/mcp-managing-virtual-keys Welcome to Albato Help Search articles # 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](https://albato.com/wiki/articles/mcp-quickstart-connecting-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. i **Note on token lifetime.** The Albato token behind a virtual key is an end-user session token, not a permanent credential. It typically expires after about a week (sometimes longer, depending on your setup). When it does, calls through that virtual key start failing with **401**. No need to issue a new virtual key when this happens: just [refresh the key](https://albato.com/wiki/articles/mcp-managing-virtual-keys#how-to-refresh-a-key) below and your agent is back up. ## 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. i If you don't have a Registration Secret yet, or aren't sure if virtual keys are set up for your contract, contact your Albato manager. ## How to register a virtual key `curl -X POST /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" }'` | Field | Required | Description | | --- | --- | --- | | albatoToken | **Yes** | Your Albato API token | | label | **No** | Human-readable name for this key (for example, **"sales-agent"**) | | expiresAt | **No** | ISO 8601 expiry date. Omit for a permanent key. | ### 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", "headers": { "Authorization": "Bearer mcp_vk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } }` ### Direct API call `curl /mcp/tools \ -H "Authorization: Bearer mcp_vk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"` See the [MCP Quickstart](https://albato.com/wiki/articles/mcp-quickstart-connecting-ai-agent) for the full connection walkthrough, and the [MCP Tools Reference](https://albato.com/wiki/articles/mcp-tools-reference) for what your agent can do once connected. ## How to manage your keys ### How to list your keys `curl /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. [](https://albato.com/wiki/articles/mcp-managing-virtual-keys) ### 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 /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 /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](https://albato.com/wiki/articles/mcp-managing-virtual-keys#refresh-a-key).** 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 | HTTP status | Meaning | | --- | --- | | 401 | Invalid, revoked, or expired virtual key / invalid Registration Secret | | 400 | Missing required field or invalid **expiresAt** (must be in the future) | | 403 | The virtual key belongs to a different contract | | 404 | Virtual key not found (refresh/revoke) | | 503 | Server unavailable. Contact your Albato manager. | Need help? Contact your Albato manager or reach out to the Albato technical team. Did this answer your question?