Platform keys are managed at /profile/api-keys, where you can create, revoke, and review them from one logged-in page. They are scoped platform auth that authenticates against Versalist itself, not external model vendors, and they are best used for CLI, MCP, and submission workflows. Keys reveal plaintext once, record last-used metadata, and revoke immediately.

Platform keys belong to Versalist. Provider keys belong to Integrations. Use platform keys when you want to authenticate the Versalist CLI, MCP mode, or challenge APIs. Use Integrations when you want Versalist to call OpenAI, Anthropic, Google, Azure, Bedrock, or other providers using your own infrastructure. Open integrations.

What a platform key is

A Versalist API key is a user-scoped credential for authenticated challenge workflows outside the browser. The key is designed for your own local shell, repo automation, editor integration, or agent host, not as a shared secret you pass around indiscriminately.

Create a key

Create keys deliberately and name them after the environment they belong to. That makes the last-used information and revocation workflow much more meaningful later.

1. Open the API keys page. Start from the logged-in management surface for platform keys. Open API keys.
2. Name the key after its environment. Use names like local-dev, claude-code, or ci-submitter so the key has obvious context.
3. Pick only the scopes the environment needs. Avoid all-scope keys by default. The value of the system is in keeping privileges narrow.
4. Copy the plaintext immediately. The raw key is shown once, so save it into the target environment before closing the dialog.

Scope design

Scope design is where most API-key quality lives. If the key only needs challenge reads, do not give it submission access. If it only needs submission access for one environment, do not treat it like a universal credential.

read:challenges

Browse challenge lists, load detail pages, export markdown, and read gold items or leaderboard data.

submit:solutions

Create challenge submissions from a local repo, script, or agent workflow.

read:submissions

Inspect your own submission history and statuses when the tooling needs that feedback loop.

Lifecycle and safety

The platform key lifecycle is intentionally tight: create the credential, reveal it once, track when it is used, and revoke it as soon as the environment no longer needs it.

One-time reveal

The plaintext key is only shown at creation time. After that, the UI stores only display-safe metadata.

Last-used tracking

Use key names and last-used timestamps together so you can tell whether an environment is still active.

Immediate revocation

If a key should no longer exist, revoke it instead of leaving it around because it might be useful later.

CLI usage

The most common place to use a platform key is your local shell for the Versalist CLI.

export VERSALIST_API_KEY=vk_live_...
versalist start dspy-optimization-challenge
versalist submit --url https://github.com/you/solution --title "Run v1"

MCP usage

The same platform key can also be attached to the CLI's MCP mode when you want Versalist available inside an editor or agent host.

{
  "mcpServers": {
    "versalist": {
      "command": "npx",
      "args": ["-y", "@versalist/cli", "mcp"],
      "env": { "VERSALIST_API_KEY": "vk_live_..." }
    }
  }
}

Name narrowly, scope narrowly, revoke quickly. Treat every platform key like a small, environment-specific contract. The tighter the contract, the easier it is to understand and the less dangerous it becomes if it is mishandled.

Related docs

Read CLI docs if you are using the key from the terminal, and read API docs if you are wiring direct HTTP. Use Integrations for provider BYOK configuration instead of platform auth.