Documentation

Management route

/profile/api-keys

Create, revoke, and review your platform keys from one logged-in page.

Key model

Scoped platform auth

These keys authenticate against Versalist itself, not external model vendors.

Primary uses

CLI, MCP, submissions

Best for terminal-native and automation-heavy challenge workflows.

Lifecycle

Reveal once, revoke fast

Keys show plaintext once, record last-used metadata, and revoke immediately.

Important distinction

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.

Credential type	Where it lives	What it does
Versalist platform key	/profile/api-keys	Authenticates the CLI, MCP mode, and challenge submission or lookup APIs.
Provider integration key	/profile/integrations	Lets Versalist route inference through your own external provider account.

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.

Open the API keys page

Start from the logged-in management surface for platform keys.

Open API keys

Name the key after its environment

Use names like local-dev, claude-code, or ci-submitter so the key has obvious context.

Pick only the scopes the environment needs

Avoid all-scope keys by default. The value of the system is in keeping privileges narrow.

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.

Scope

read:challenges

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

Scope

submit:solutions

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

Scope

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_..." }
    }
  }
}

Good key hygiene

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.

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.

API Keys

What a platform key is

Create a key

Scope design

Lifecycle and safety

CLI usage

MCP usage

Related docs