API keys

Summary#

An API key lets a script or another system call Metric Vault without a browser session. Keys are an Enterprise plan capability, they begin with mv_live_, each account can hold five active keys at a time, and the full key is shown once at creation and never again. Every call made with a key spends credits from the owning account's monthly allowance, exactly as if it had been run in the app.

Purpose#

Everything else in Metric Vault assumes a person at a keyboard. An API key exists for the cases where that is the wrong shape: pulling a domain analysis into a client dashboard, running a check as part of a nightly pipeline, or feeding results into a reporting warehouse. Because the key acts on behalf of a paying account and spends its credits, it is deliberately limited: one endpoint, no scopes, a hard cap on how many can exist, and an instant revoke.

Requirements#

• The Enterprise plan. Every key operation, including creating one and using one, re-checks the account's current plan.
• Credits available in the account's monthly allowance. A call that would exceed the quota is refused.
• Somewhere secure to keep the key. It is displayed once.

Permissions#

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

There are no scopes. A key is a single credential with one capability: it can call the analysis endpoint. It cannot read your Library, change settings, manage a team or touch billing.

Navigation Path#

There is no key-management screen in the dashboard today. Keys are managed through three endpoints, and Enterprise customers who would rather not script it should ask support@metricvaultai.com to provision one.

The management endpoints authenticate with your Metric Vault session, not with an API key:

Authentication covers the mechanics in full.

Step-by-Step Guide#

Create a key#

1. Confirm the account is on the Enterprise plan. The Plan tile on the Account screen shows the current plan.
2. Call POST /api/keys/create with your session token and a label. The label is optional; it defaults to API key and is trimmed to 60 characters.
3. The response contains the full key, for example mv_live_3f9a1c7d4b28e05a6f13c9d720b48e1a5c6d7f0293a4b1c8.
4. Copy it now. The response is the only time the full value is returned. Store it in your secret manager or environment configuration.
5. The action is recorded on your account activity feed as Created an API key.

If the account already holds five active keys, the request is refused with Key limit reached (5 active keys). Revoke one first. If the session token is missing or invalid, the response is Unauthorized. If the account is not on Enterprise, the response explains which plan is required and links to the pricing page.

Use a key#

Send the key as a bearer token on the analysis endpoint:

POST https://metricvaultai.com/api/v1/analyze
Authorization: Bearer mv_live_...
Content-Type: application/json

{ "url": "example.com" }

The response contains the domain analysis. Each call costs 6 credits from the owning account's monthly allowance and updates the key's last-used timestamp.

Error responses you may see:

List your keys#

Call POST /api/keys/list. Each key comes back as:

The full key is never returned by this endpoint. If you have lost a key, revoke it and create a new one.

Revoke a key#

1. Call POST /api/keys/list to find the id of the key you want to remove.
2. Call POST /api/keys/revoke with that id.
3. The key stops working immediately. Any request using it afterwards receives Invalid or revoked API key.

Revoking is permanent and cannot be undone: revoked keys cannot be reactivated. Create a new key instead. Revoked keys still appear in the list, marked as revoked, so you keep the record of what existed. The action is recorded on your account activity feed as Revoked an API key.

Examples#

Screenshots#

Tips#

• Give every key a label that says where it runs, such as ci-pipeline or client-portal-prod. With a five-key cap and masked listings, the label is how you tell them apart.
• Store keys in a secret manager, never in source control or a shared document.
• Rotate deliberately: create the replacement, deploy it, confirm traffic has moved by watching last_used_at, then revoke the old key.
• Budget the credits before you automate. Six credits per call adds up quickly in a loop. See How credits work.
• Handle the quota and plan responses in your client. They are ordinary responses, not network failures, and retrying immediately will not help.

Common Mistakes#

• Not saving the key at creation. The full value is returned once. If it is lost, the only remedy is to revoke and create another.
• Assuming a key survives a downgrade. Every call re-checks the current plan. Leave Enterprise and the keys stop working, even though they still exist.
• Expecting scopes. There are none. Anyone holding the key can spend the account's credits on the analysis endpoint.
• Hitting the cap silently. The sixth creation attempt fails with Key limit reached (5 active keys). Revoke one first. Revoke unused keys as part of housekeeping.
• Running a tight loop. Metered calls count against the monthly allowance and against rate limits. See Rate limits and quotas.

Limitations#

• Enterprise plan only.
• Five active keys per account.
• One endpoint, /api/v1/analyze. Keys do not unlock the rest of the platform.
• No scopes, no per-key credit budgets, no per-key rate limits.
• No key-management screen in the dashboard today.
• Keys do not expire on their own. Rotate them on your own schedule.
• Revoking is one-way.

Troubleshooting#

FAQs#

Can I see a key again after creating it? No. The list endpoint returns a masked form only, such as the first twelve characters, an ellipsis and the last four. If the full key is lost, revoke it and create a new one.

Do API calls cost credits? Yes. Each analysis call costs 6 credits from the owning account's monthly allowance, and appears in the usage figures on the Account screen alongside runs made in the app.

Can I restrict a key to one domain or one IP address? No. Keys carry no scopes or restrictions. Protect them the way you would protect any production secret.

What happens to keys if the account downgrades? The keys remain in the account's list, but calls stop working because the plan is re-checked on every call. Returning to Enterprise makes the existing keys work again.

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

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