Proposal: API-first management for OmniRoute — management-scoped API keys & settings endpoints

[shannonlowder]

Summary

Current behaviour: OMNIROUTE_TOKEN (public API key) authenticates /api/v1/* proxy endpoints, while dashboard management endpoints (e.g. /api/pricing, /api/settings/*) require a dashboard session JWT cookie or server-signed session token. This prevents programmatic management of settings (model pricing, providers, combos, etc.).

Proposal

Add a management API (or extend existing management routes) to support programmatic admin actions with scoped, auditable tokens so anything doable in the UI is automatable.

Key design questions for maintainers

1. Do maintainers want an official management API or keep management UI-only?
2. Preferred approach:
   • accept scoped Bearer tokens on existing /api/* management routes,
   • a new /api/management/* namespace, or
   • both for compatibility?
3. Scope model: coarse (admin / read-only) or fine-grained (pricing, providers, combos, backups, audit)?
4. Audit, rotation, revocation, and rate-limiting policy for management tokens?
5. Any constraints (external IAM, storage policies) we should honour?

Security must-haves

• Scoped management tokens (least privilege).
• Token rotation + revocation UI + audit trail for all management API calls.
• Enforce HTTPS, CORS, strong validation (Zod already used), and pre-write DB backups (backupDbFile("pre-write") is already used).
• Rate-limits and circuit-breaker for admin APIs.
• Management token creation/revocation guarded by dashboard session.

Implementation outline (high level)

1. management_tokens table: id, secret_hash, scopes, name, created_by, revoked_at.
2. Extend verifyAuth() to accept management Bearer tokens and validate scopes for routes.
3. Add endpoints to create/list/revoke management tokens (dashboard + API), protected by session auth.
4. Expose one pilot endpoint (e.g., PATCH /api/pricing) with tests and docs.
5. Add unit/e2e tests and rollout docs.

Offer

I can sponsor/contract implementation. If maintainers want this, I can prepare an RFC/PR (token schema, scope list, and a pilot PR for pricing).

Next steps / Questions

• Who should I loop in for a design review?
• Prefer an RFC before PR?
• Any hard constraints I should account for?

Suggested labels: idea, api, security, help-wanted

[diegosouzapw]

Hey @shannonlowder!
Thank you for this detailed proposal. An API-first approach for the management endpoints with scoped tokens is an excellent idea and aligns perfectly with our vision of making OmniRoute easily automatable.
We would love to see an RFC and a PR for this. A coarse scope model (admin / read-only) is probably the best starting point to keep the initial implementation manageable. Using Bearer tokens on existing management routes via verifyAuth() sounds like a solid approach.
I have opened an issue to track this feature request. Follow along there for updates!

[shannonlowder]

Thanks, Diego — this helps clarify the direction. I can absolutely align with the “coarse scope + minimal surface” approach. To make sure I’m tracking correctly, here’s the plan I’ll follow for the RFC and eventual PR:

1. Scope model (MVP)

• admin — full access to existing management routes
• read-only — GET‑only access to the same routes

No granular scopes, no per‑resource permissions — just the minimal two‑tier model you suggested.

2. Token model

• New management tokens stored hashed (similar to API keys)
• Passed via Authorization: Bearer
• Verified through a small extension of verifyAuth()

Dashboard session auth remains unchanged

3. API surface (MVP)

• No new endpoints initially — just enabling Bearer‑token access to:
• /api/providers/*
• /api/combos/*
• /api/settings/* (read‑only for now)

This keeps the first PR small and low‑risk.

4. RFC content
   I’ll draft an RFC that includes:

• Problem statement
• Proposed minimal design
• Security considerations
• Migration / backward compatibility
• Future extensions (fine‑grained scopes, token metadata, audit logs)

I’ll keep it short and focused so it’s easy to review.

5. PR approach
   Once the RFC looks good, I’ll open a PR implementing:

• Token creation + hashing
• Scope enforcement
• Bearer‑token auth path in verifyAuth()
• Tests for admin vs read‑only behavior

Happy to iterate on the design as needed — the goal is to land a clean, maintainable foundation you can build on.

[shannonlowder]

RFC: Management‑Scoped API Tokens for OmniRoute

Author: Shannon
Status: Draft
Related Issues: #1567, #1568
Target Release: TBD
Reviewers: OmniRoute maintainers

---

1. Summary

This RFC proposes adding management‑scoped API tokens to OmniRoute, enabling programmatic access to existing management routes using a simple, coarse‑grained permission model:

• admin — full access to all management routes
• read-only — GET‑only access

Tokens authenticate via:
Authorization: Bearer <management_token>

The goal is to unlock automation workflows (CI/CD, agent orchestration, infrastructure provisioning) while keeping the initial implementation small, safe, and maintainable.

---

2. Motivation

OmniRoute currently exposes management functionality only through:

• the dashboard (session‑based auth)
• direct edits to data/db.json (not automatable or safe)

This limits automation for:

• provisioning providers/combos in CI/CD
• rotating provider API keys
• enabling/disabling providers based on health checks
• syncing settings across multiple OmniRoute instances
• agent‑driven dynamic routing adjustments

A minimal management API with scoped tokens enables these workflows without expanding the attack surface or requiring new endpoints.

---

3. Goals

3.1. Primary Goals (MVP)

• Introduce management tokens with two scopes:
  • admin
  • read-only
• Allow Bearer‑token authentication on existing management routes
• Reuse and extend verifyAuth() for token validation
• Store tokens securely (hashed) inside db.json
• Provide CRUD operations for tokens

3.2. Non‑Goals (for future RFCs)

• Fine‑grained per‑resource scopes
• Audit logs
• Token metadata (IP restrictions, expiration policies)
• New management endpoints beyond token CRUD

---

4. Design Overview

4.1. Data Model (JSON‑backed)

Add a new top‑level key in data/db.json:

{
  "managementTokens": [
    {
      "id": "cuid",
      "name": "ci-cd",
      "scope": "admin",
      "hash": "<hashed-secret>",
      "createdAt": "2026-04-24T00:00:00Z",
      "lastUsedAt": null,
      "revokedAt": null
    }
  ]
}

This mirrors how providers, combos, and settings are already stored.

4.2. Token Generation

-User creates a token via dashboard or API
-OmniRoute returns the plaintext token once

• Only the hash is stored in db.json

Token format example:
omni_mgmt_<random_32_bytes>

4.3. Authentication Flow

Extend verifyAuth():

1. If Authorization: Bearer is present:

• Hash the token
• Look up matching entry in managementTokens
• Validate scope
• Attach authContext = { type: "token", scope }

2. Else fall back to existing session‑based auth

4.4. Scope Enforcement

ope	Allowed Methods
read-only	GET
admin	GET, POST, PATCH, DELETE

Applied uniformly across existing management routes:

• /api/providers/*
• /api/combos/*
• /api/settings/* (GET only for now)

4.5. Token CRUD Endpoints

New endpoints under /api/management/tokens:

POST   /api/management/tokens
GET    /api/management/tokens
DELETE /api/management/tokens/:id

5. Security Considerations

• Tokens stored hashed (bcrypt or scrypt)
• Tokens never shown again after creation
• lastUsedAt updated on each request
• Rate limiting applies to token‑authenticated routes
• No privilege escalation: scopes are coarse and enforced centrally

6. Backward Compatibility

• No breaking changes
• Existing dashboard and session auth remain unchanged
• Existing management routes require no modification beyond auth branching

7. Future Extensions (not part of MVP)

• Fine‑grained scopes (providers:write, combos:read, etc.)
• Token expiration and rotation policies
• Audit logs for management actions
• Service‑to‑service identity (mTLS, JWT‑based auth)

8. Implementation Plan

Phase 1: RFC Review

• Validate scope model
• Validate token CRUD endpoints
• Validate reuse of existing management routes

Phase 2: PR Implementation

• Add managementTokens to db.json schema
• Add token CRUD endpoints
• Extend verifyAuth()
• Add scope enforcement middleware
• Add tests for:
  • admin vs read‑only
  • token hashing
  • Bearer‑token auth path
  • dashboard session fallback

Phase 3: Documentation

• Add “Management Tokens” section to OmniRoute docs
• Provide examples for CI/CD and automation

9. Open Questions

• Should tokens support optional expiration?
• Should settings write access be included in MVP or deferred?
• Should token names be required or optional?

10. Conclusion

This RFC proposes a minimal, maintainable foundation for programmatic management of OmniRoute. It aligns with the maintainers’ guidance (coarse scopes, Bearer tokens, reuse of existing routes) while enabling real‑world automation and orchestration use cases.

Feedback welcome — happy to adjust the scope or implementation details based on maintainer input.

[diegosouzapw]

I've opened Issue #1605 to track this feature request formally. Follow along there for updates!

#1605

[shannonlowder]

@diegosouzapw:

I hope this message finds you well. I noticed that issue 1605 I raised has been closed with the note that the API-first management feature is being tracked internally for a future release.

I’ve completed the code changes for this feature and am finalizing unit test coverage, along with a few integration tests to ensure we can use the API effectively. Given the internal tracking, I’m uncertain about the timeline for this feature’s release.

I would love to contribute to the community by adding this feature without forking the repository. Could you please share your thoughts on how we might move this feature forward? I appreciate any guidance you can provide!

Thank you for your time!

[diegosouzapw]

Hi @shannonlowder
Excellent proposal! This is very well thought out and aligns with where we want to take OmniRoute.

What's already available today:
OmniRoute ships with an MCP Server (29 tools) that provides programmatic access to many management functions -- combo management, health checks, routing, metrics, budget controls, and more. This can be used from any MCP-compatible client for automation.

What this proposal adds:
A dedicated REST management API with scoped API keys is the natural next step. It would enable:

• CI/CD integration without MCP dependency
• • Infrastructure-as-code workflows
• • Third-party monitoring integration
• • CLI scripting for batch operations
    I'm creating a formal GitHub Issue from this discussion to track implementation. Thank you for the detailed specification -- it gives us a great foundation to work from!