Skip to main content
Agent skill

Omni Api Keys

Create, list, rotate, and revoke OmniRoute API keys. Control per-key scopes, spending limits, and expiration. Keys gate access to all proxy and management endpoints.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Omni Api Keys when an AI agent needs a reusable SKILL.md workflow for this job: Create, list, rotate, and revoke OmniRoute API keys. Control per-key scopes, spending limits, and expiration. Keys gate access to all proxy and management endpoints.

When not to use it

Skip Omni Api Keys when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/omni-api-keys
# Save SKILL.md to ~/.claude/skills/omni-api-keys/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/omni-api-keys/SKILL.md. For a shared project, commit the folder at .claude/skills/omni-api-keys/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Omni Api Keys skill for this task: Use Omni Api Keys when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

## Overview

Create, list, rotate, and revoke OmniRoute API keys. Control per-key scopes, spending limits, and expiration. Keys gate access to all proxy and management endpoints.

## Authentication

All requests require a valid Bearer token or session cookie. Obtain a token via `POST /api/auth/login` or configure `REQUIRE_API_KEY=false` for local development.

## Endpoints

### GET /api/keys

List API keys

```bash curl http://localhost:20128/api/keys \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### POST /api/keys

Create API key

Submit the legacy key settings, or name with a complete policy and optional templateRef containing id and revision. Policy-based creation writes the key and related settings atomically. Submitted edits are final; templateRef is provenance and never replaces the policy. The fresh secret is returned once with Cache-Control no-store. Blocking missing references return 422.

```bash curl -X POST http://localhost:20128/api/keys \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### GET /api/keys/{id}/template-policy

Preview a key policy without revealing its credential

```bash curl http://localhost:20128/api/keys/{id}/template-policy \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### POST /api/keys/import

Import a caller-supplied API key without replacing existing keys

Uses the same management authentication as POST /api/keys: dashboard session, local CLI credential, manage/admin-scoped API key, or an admin oma_ access token. read/write oma_ tokens are insufficient. When login is disabled, inference-only imports may be anonymous, but importing manage/admin scopes requires a real management credential, including retries against an existing management-scoped key.

Accepts a 32–256 character ASCII key beginning with sk-, followed only by A–Z, a–z, 0–9, underscore or hyphen. No machine-id or CRC validation is performed. Whitespace is rejected, never trimmed. Configured environment API keys and the internal self-loop credential cannot be imported because they bypass row policy.

An explicit existing id with the same key hash returns 200 and the existing stored policy without mutation; requested name/policy changes are ignored. An existing id with a different value, or the same value at another id, returns 409 without disclosing another id. Without id, a UUID is generated and duplicate values return 409, not 200. New imports return 201. No rekey is performed.

Identity checks and the complete policy insert run in one synchronous SQLite IMMEDIATE transaction. Uses create-key defaults and scope normalization (adds self:usage and removes duplicates). Unknown fields, including isActive, are ignored just as on create; change active state through the existing PATCH route. No settings, providers, combos or session state is imported. This does not change the operator-only import-json restore permissions. Cloud sync is best-effort and asynchronous for new imports only. Secrets use enc:v1 encryption at rest when storage encryption is configured; otherwise upstream plaintext storage applies. Responses contain only id/name, a masked key and whitelisted stored policy fields, never the full secret, hash, key prefix column or machine identifier.

```bash : "${IMPORTED_API_KEY:?Set the caller-supplied sk- key to import}" curl -X POST http://localhost:20128/api/keys/import \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -d "{\"name\":\"Imported key\",\"key\":\"$IMPORTED_API_KEY\"}" ```

### GET /api/keys/{id}

Get API key

```bash curl http://localhost:20128/api/keys/{id} \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### PATCH /api/keys/{id}

Update API key

```bash curl -X PATCH http://localhost:20128/api/keys/{id} \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### DELETE /api/keys/{id}

Delete API key

```bash curl -X DELETE http://localhost:20128/api/keys/{id} \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### POST /api/keys/{id}/access

Add or remove allowed models and combos on an API key atomically

Adds or removes allowed models and combos on an API key without lost updates. Serialized per key ID using an in-process async lock. Keys allowing all models (modelAccessMode: all) or all combos (allowedCombos containing 'combo/*') require switchToRestricted: true when adding new models or combos, otherwise returning a 409 Conflict. When switching to restricted mode, the allowlist becomes exactly the net added items (at least one required). Direct concurrent PATCH calls to /api/keys/{id} completely overwrite the policy outside this lock.

```bash curl -X POST http://localhost:20128/api/keys/{id}/access \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### GET /api/keys/{id}/devices

List devices for an API key

Lists the distinct devices (masked IP + User-Agent fingerprints) tracked for an API key by the in-memory device tracker. IPs are masked before storage; the route never sees the raw client IP.

```bash curl http://localhost:20128/api/keys/{id}/devices \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### POST /api/keys/{id}/regenerate

POST keys › <id> › regenerate

```bash curl -X POST http://localhost:20128/api/keys/{id}/regenerate \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### GET /api/keys/{id}/reveal

GET keys › <id> › reveal

```bash curl http://localhost:20128/api/keys/{id}/reveal \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### GET /api/keys/{id}/usage-limits

GET keys › <id> › usage limits

```bash curl http://localhost:20128/api/keys/{id}/usage-limits \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### GET /api/keys/{id}/self-service

GET keys › <id> › self service

Self-service settings, what the key holder can see through /v1/me/status, the providers the key can reach, and an admin preview of its /v1/me/status body (always includes limits and settings-filtered accountQuotas, regardless of scopes).

```bash curl http://localhost:20128/api/keys/{id}/self-service \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### PUT /api/keys/{id}/self-service

PUT keys › <id> › self service

Update the key's self-service settings. Omitted fields keep their value.

```bash curl -X PUT http://localhost:20128/api/keys/{id}/self-service \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### GET /api/keys/groups

GET keys › groups

```bash curl http://localhost:20128/api/keys/groups \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### POST /api/keys/groups

POST keys › groups

```bash curl -X POST http://localhost:20128/api/keys/groups \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### GET /api/keys/groups/{id}

GET keys › groups › <id>

```bash curl http://localhost:20128/api/keys/groups/{id} \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### PUT /api/keys/groups/{id}

PUT keys › groups › <id>

Updates the group. Setting isActive to false pauses its allow rules while preserving membership restrictions and deny rules. Other active groups may still grant access unless a deny matches. Keys belonging only to inactive groups have no group grants. Keys without groups remain unrestricted by group policy; per-key restrictions still apply.

```bash curl -X PUT http://localhost:20128/api/keys/groups/{id} \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### DELETE /api/keys/groups/{id}

DELETE keys › groups › <id>

```bash curl -X DELETE http://localhost:20128/api/keys/groups/{id} \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### GET /api/keys/groups/{id}/keys

GET keys › groups › <id> › keys

```bash curl http://localhost:20128/api/keys/groups/{id}/keys \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### POST /api/keys/groups/{id}/keys

POST keys › groups › <id> › keys

```bash curl -X POST http://localhost:20128/api/keys/groups/{id}/keys \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### DELETE /api/keys/groups/{id}/keys

DELETE keys › groups › <id> › keys

```bash curl -X DELETE http://localhost:20128/api/keys/groups/{id}/keys \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### GET /api/keys/groups/{id}/permissions

GET keys › groups › <id> › permissions

```bash curl http://localhost:20128/api/keys/groups/{id}/permissions \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

### POST /api/keys/groups/{id}/permissions

POST keys › groups › <id> › permissions

```bash curl -X POST http://localhost:20128/api/keys/groups/{id}/permissions \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ```

### DELETE /api/keys/groups/{id}/permissions

DELETE keys › groups › <id> › permissions

```bash curl -X DELETE http://localhost:20128/api/keys/groups/{id}/permissions \ -H "Authorization: Bearer $OMNIROUTE_TOKEN" ```

## Payloads

See the full OpenAPI specification at `GET /api/openapi/spec` or `docs/openapi.yaml` for detailed request/response schemas.

Intended uses

  • Use Omni Api Keys when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.