Authentication

Summary#

The public API is authenticated with a bearer key that begins with mv_live_. You create a key by calling POST /api/keys/create with your Metric Vault session token, and you then use that key on POST /api/v1/analyze in an Authorization: Bearer header. The full key is returned exactly once at creation. Each account can hold five active keys, and every key operation requires the Enterprise plan.

Note that there are two different credentials in play. The three key-management endpoints authenticate with your session token, because they are account operations. The analysis endpoint authenticates with the API key, because it is a machine operation.

Purpose#

An API key exists so a script can act for your account without a browser. It is deliberately dull: no scopes, no expiry, no per-key budgets, one capability. The management endpoints require a live human session precisely because minting a credential that can spend an account's credits should not itself be doable with a credential that spends credits.

Requirements#

• The Enterprise plan on the account that will own the key. The plan is checked at creation and again on every call the key makes.
• A signed-in Metric Vault session, so you can obtain a session token for the management calls.
• Fewer than five active keys on the account. Revoked keys do not count.
• Somewhere secure to store the returned key. It is shown once.

Permissions#

Keys belong to the account that created them. The account owner is the only person who can create, list or revoke that account's keys. Team members do not inherit access to a workspace owner's keys, they are not visible to members, and there is no administrator action that issues a key on a customer's behalf.

There are no scopes. Anyone holding the key can call the analysis endpoint and spend the owning account's credits. It cannot read your Library, change settings, manage a team, or touch billing.

Navigation Path#

There is no key-management screen in the dashboard. Authentication is set up entirely through three endpoints:

POST /api/keys/create → POST /api/keys/list → POST /api/keys/revoke

Enterprise customers who would rather not script this can ask support@metricvaultai.com to provision a key.

Step-by-Step Guide#

1. Get a session token#

The management endpoints take your Metric Vault session access token in the JSON body, as the field token. It is the same token your browser holds after you sign in.

To read it from a signed-in browser, open the developer console on https://metricvaultai.com/dashboard and run:

// The session is stored under the only key matching sb-<project>-auth-token
const k = Object.keys(localStorage).find(k => /^sb-.*-auth-token$/.test(k));
JSON.parse(localStorage.getItem(k)).access_token;

2. Create a key#

curl -X POST https://metricvaultai.com/api/keys/create \
  -H "Content-Type: application/json" \
  -d '{
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.PASTE_YOUR_SESSION_TOKEN",
        "name": "nightly-refresh"
      }'

A successful response:

{
  "ok": true,
  "key": "mv_live_3f9a1c7d4b28e05a6f13c9d720b48e1a5c6d7f0293a4b1c8",
  "name": "nightly-refresh"
}

The response carries Cache-Control: no-store. Copy the key value now. This is the only time the full key is returned. The action is recorded on your account activity feed as Created an API key.

Key format: the literal prefix mv_live_ followed by 48 hexadecimal characters, 56 characters in total, generated from 24 cryptographically random bytes.

3. Use the key#

Send it as a bearer token on the analysis endpoint:

curl -X POST https://metricvaultai.com/api/v1/analyze \
  -H "Authorization: Bearer mv_live_3f9a1c7d4b28e05a6f13c9d720b48e1a5c6d7f0293a4b1c8" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}'

The header is parsed as the literal string Bearer followed by the key. Any other scheme, or a missing header, is rejected before the key is looked up. Full request and response detail is in POST /api/v1/analyze.

4. List your keys#

curl -X POST https://metricvaultai.com/api/keys/list \
  -H "Content-Type: application/json" \
  -d '{"token": "PASTE_YOUR_SESSION_TOKEN"}'

{
  "ok": true,
  "keys": [
    {
      "id": 7,
      "name": "nightly-refresh",
      "masked": "mv_live_3f9a…b1c8",
      "created_at": 1754438400000,
      "last_used_at": 1754524800000,
      "revoked": false
    }
  ]
}

Keys are returned newest first. The full key is never returned here. If you lose a key, revoke it and create a new one.

5. Revoke a key#

curl -X POST https://metricvaultai.com/api/keys/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "PASTE_YOUR_SESSION_TOKEN", "id": 7}'

{ "ok": true }

The key stops working immediately. Any later request using it receives Invalid or revoked API key with HTTP 401. Revocation is a soft delete: the key remains in the list marked revoked: true, so you keep the record, but it no longer counts against the five-key cap.

The action is recorded on your account activity feed as Revoked an API key.

6. Rotate on a schedule you choose#

Keys do not expire on their own. A safe rotation is: create the replacement, deploy it, watch the new key's last_used_at advance and the old key's go stale, then revoke the old key.

Errors#

Every code the platform can return is listed in Error codes.

Troubleshooting#

FAQs#

Can I see a key again after creating it? No. POST /api/keys/list returns a masked form only. If the full value is lost, revoke that key and create a new one.

Do keys expire? No. They live until revoked, or until the account leaves the Enterprise plan, at which point calls fail while the key itself remains listed.

Can I restrict a key to one IP address, one domain or one endpoint? No. There are no scopes or restrictions of any kind. Protect the key the way you would protect a production database password.

Is the session token interchangeable with an API key? No. The three management endpoints accept only a session token, and the analysis endpoint accepts only an mv_live_ key. A session token sent to /api/v1/analyze is rejected as an invalid key.

Can a team member use the workspace owner's key? Only if the owner hands it to them. Keys are not shared through team membership.

Is there a test key or sandbox? No. There is one key type and calls run against live data and spend real credits.

What is logged when a key is used? The key's last_used_at timestamp is updated, and the credit spend appears in the account's monthly usage under the tool name domain_overview. Creation and revocation appear in the account activity feed.