API Keys | Versalist Documentation

A Versalist API key authenticates supported requests outside the browser. Each key belongs to one user and has explicit scopes. Some routes, including starting a hosted run and changing the retention policy, accept only a signed-in session; the API reference marks each one.

Platform keys and provider credentials

Credential	Management page	Purpose
Versalist API key	/profile/api-keys	Authenticates the CLI, MCP server, and supported Versalist APIs.
Provider credential	/profile/integrations	Authorizes supported model calls through an external provider account.

Scopes

A key has nine possible scopes. Grant only what the tool needs. Live keys start with vk_live_.

If you want to…	Grant
Follow the quickstart: load a challenge and submit	`read:challenges`, `submit:solutions`
Let an MCP host list your submissions	`read:submissions`
Run an open-weight model locally, or build your own runner	`submit:solutions` (or `read:runs` + `execute:runs`)
Read saved execution records and environment versions	`read:challenges`
Run sweeps and replays against saved records	`submit:solutions`
Read findings, proposed changes, comparisons, and workspace metrics	`read:governance`
Save a failure, propose a change, request a decision or release	`write:governance`
Search, pull, or publish Skill Exchange bundles	`read:skills`, `write:skills`

Challenge and submission scopes

read:challenges

List and fetch challenge details, markdown, gold examples, and leaderboards.

submit:solutions

Create challenge submissions and start local model runs.

read:submissions

Read the key owner's submission history. Required for MCP get_my_submissions.

Run and governance scopes

Not yet selectable in the Developer API page

The key creation page lists the five challenge, submission, and skill scopes. The four scopes below are accepted by the key API and enforced by the routes, but the page does not offer them yet. Until it does: use submit:solutions for the run protocol, which the routes accept as an alternative, and call the comparison and release routes from a signed-in browser session, which the web app already does.

read:runs

Read run protocol status and the runs your own runner created at /api/v1/runs. A key with submit:solutions can do the same.

execute:runs

Create, claim, heartbeat, report, and cancel runs through /api/v1/runs. A key with submit:solutions can do the same.

read:governance

Read saved findings, proposed skill changes (amendments), registered comparisons, signed lineage exports, and the workspace metrics behind Governance.

write:governance

Save a failure as a test case, propose a change, register a comparison, request a decision, record a release or rollback, and cancel a background environment run. Treat this like a deploy credential: it records decisions in your workspace's release history.

read:skills

Search, pull, and report outcomes on Skill Exchange skills. Used by vskill.

write:skills

Publish, version, and suggest Skill Exchange skills. Used by vskill push and vskill suggest.

Create a key

Open Developer API.
Enter a name that identifies the environment.
Select only the required scopes.
Create the key.
Copy the plaintext value immediately.

The page shows the plaintext value one time.

Store a key

Store local keys in an environment variable or approved secret manager.
Store continuous integration keys in the platform secret store.
Do not put a key in source code.
Do not commit a key to source control.
Do not expose a key in client-side code.

Use a key with the CLI

export VERSALIST_API_KEY=vk_live_...
versalist list
versalist start agentic-code-optimization-review

Read the CLI guide for command requirements and output files.

Use a key with MCP

Model Context Protocol (MCP) mode reads the same environment variable. Export the key before you start the MCP host.

export VERSALIST_API_KEY=vk_live_...
npx -y @versalist/cli mcp

Each MCP host uses a different configuration format. Select your host in the coding agent guides. The tools themselves are on MCP tools. Use a second key with skill scopes for vskill.

Rotate a key

Create a replacement key with the same required scopes.
Update the target environment.
Test the replacement key.
Revoke the old key.

Revoke a key

Revoke a key immediately when it is exposed, unused, or assigned to a retired environment.

Open API keys.
Find the key by name and last-use time.
Revoke the key.
Confirm that dependent requests now fail.