Cortensor Portal V1 Detailed Spec 03 - API Key Management

Status

Draft

Purpose

This document defines the API key layer for Cortensor Portal V1.

It covers:

• what Portal API keys are for

• key lifecycle rules

• key ownership model

• dashboard flows for creating and revoking keys

• the relationship between Portal keys, Unkey, and the backend gateway

This spec is focused on the product-facing API key layer, not low-level router credentials or internal service secrets.

---

1. Summary

Portal V1 should expose a Portal-owned API key layer for hosted inference access.

Users should be able to:

• create a key

• reveal it once

• copy it

• view existing keys in masked form

• revoke keys they own

Portal API keys should be clearly distinct from:

• raw router-node keys

• dashboard auth sessions

• internal service credentials

The user should experience Portal keys as a normal hosted API product primitive, not as a direct reflection of Cortensor router internals.

---

2. Goals

Portal V1 API key management should aim to:

• make hosted API access easy to start using

• keep key UX simple and productized

• support key verification and revocation cleanly

• support free-plan and per-key rate-limit enforcement

• preserve room for richer metadata and policy later

---

3. Non-Goals

The API key layer for V1 should not attempt to solve everything.

Explicit non-goals for V1 include:

• exposing raw router credentials directly to customers

• shipping complex per-key scopes in the first release

• supporting advanced key hierarchy or delegation from day one

• exposing internal gateway or router topology via the key model

• building an enterprise-style secrets management product inside Portal

---

4. Key Ownership Model

Each Portal API key should belong to:

• a user account, or

• an organization account if org support is enabled in scope

The backend must enforce:

• only authorized owners can list keys

• only authorized owners can revoke keys

• create and revoke actions are audited

• key visibility is limited to the owning account context

Ownership should be treated as Portal product ownership, not raw infrastructure ownership.

---

5. What Portal API Keys Are For

Portal API keys are the credentials used by customers to access the hosted Cortensor API.

Their role is to let the gateway identify:

• which account is calling

• whether the request is allowed

• which plan / quota / rate-limit policy applies

• which model access rules apply

Portal API keys should not be treated as:

• router admin credentials

• internal service-to-service credentials

• direct session-level network credentials

Portal keys are product-facing keys used at the Portal/gateway layer.

---

6. Recommended V1 Key Fields

Suggested durable metadata:

• key_id

• owner_user_id

• owner_organization_id (if applicable)

• display_name

• key_prefix

• key_hash or external verification reference

• status

• created_at

• revoked_at

• last_used_at later if simple enough

Important Rule

The raw secret should not be stored in retrievable plaintext in Portal durable state.

The UI should reveal the secret once at creation time, then only show masked form later.

This is a core product rule for V1.

---

7. Key Lifecycle

7.1 Create

Expected flow:

1. authenticated user opens the create-key flow

2. user enters a key name

3. backend verifies:

   • account ownership

   • plan allowance

   • optional key-count limits

4. key is created through the key-management path

5. raw secret is returned once

6. durable metadata is written

7. user is prompted to copy/store the key immediately

7.2 List

The dashboard should list:

• key name

• masked value or prefix

• created time

• status

Optional later:

• last used

• tags / notes

• environment labels

7.3 Revoke

Expected flow:

1. user selects revoke

2. destructive confirmation appears

3. backend verifies ownership

4. key is revoked

5. dashboard updates state

7.4 Reveal After Creation

Portal should not support re-revealing the full secret later.

If a user loses the secret, they should create a new key and revoke the old one.

---

8. Relationship to Unkey

For V1, Unkey is a strong fit for:

• key issuance support

• verification

• revocation-aware validation

• rate limiting

• fast hot-path checks

Portal should still own:

• ownership model

• product semantics

• model entitlement logic

• durable metadata

• durable usage writeback

• account / org mapping

• key management UX

Unkey is a supporting enforcement layer, not the entire product control plane.

Practical Split

Unkey handles:

• key verification

• fast request-time key checks

• rate-limit support

• revocation-aware hot-path behavior

Portal backend handles:

• who owns the key

• whether the account is allowed to create more keys

• what models the key’s owner can access

• what plan/quota semantics apply

• writing durable metadata and usage records

---

9. Key UX Requirements

The API Keys page should support:

• empty state if no keys exist

• create-key CTA

• masked existing key cards or rows

• revoke action

• copy action on the reveal screen

• simple explanatory copy

9.1 Create-Key Dialog Requirements

The create flow should include:

• field for key name

• create action

• success state with one-time full secret

• clear warning that the secret will not be shown again

9.2 Revoke Flow Requirements

The revoke flow should include:

• confirm dialog

• clear irreversible warning

• success feedback

• visible state update after revocation

9.3 Empty State

If no keys exist:

• clear message

• one prominent Create API Key CTA

• optional quick-start docs link

9.4 V1 Success Criteria

The API key UX should make it possible for a user to:

• create a usable key in under a minute

• understand which keys are active

• understand that secrets are reveal-once

• understand revoke behavior without ambiguity

---

10. Usage and Rate-Limit Relationship

Portal V1 should assume:

• keys are valid credentials for hosted API calls

• rate limits can apply per key

• quota checks can also apply at the account or organization level

This means:

• a key being valid does not guarantee allowance remains

• gateway checks still must happen after key verification

• key verification and usage allowance are related, but not the same thing

In practical terms:

• Unkey (or equivalent hot-path key layer) can say:

  • “this key is real / active / revoked / rate-limited”

• Portal backend / gateway logic still decides:

  • “does this account still have quota?”

  • “is this model available for this account?”

  • “should this request be accepted right now?”

---

11. Recommended V1 Constraints

Portal V1 may optionally enforce simple product constraints such as:

• max active key count per free-plan account

• key name length constraints

• soft naming rules

These should stay simple and easy to explain.

Examples:

• free plan can only keep a limited number of active keys

• key names must be short enough for clean UI display

• duplicate names may be allowed or lightly discouraged depending on implementation choice

---

12. Error Cases

Important user-facing cases include:

• key creation failed

• too many keys for current plan

• key already revoked

• revoke failed

• raw secret not available anymore

Messages should be:

• clear

• product-oriented

• action-oriented where possible

Examples of message tone:

• “You’ve reached the maximum number of active keys for your current plan.”

• “This key has already been revoked.”

• “The full secret is only shown once. Create a new key if you need another one.”

---

13. Future Extensions

Good later additions:

• last used timestamp

• notes or tags

• usage by key

• model allowlists by key

• environment labels such as dev or production

• org-owned keys with richer permission semantics

• per-key analytics and audit views

These are useful but should not block V1.

---

14. Open Questions

Open questions for later refinement:

• should the free plan cap total active keys?

• should key names be unique per owner?

• should org-owned keys be in V1 or later?

• how much per-key usage visibility should be surfaced in V1?

• should Portal support test vs live key modes in V1 or later?

---

15. Relationship to Other Specs

This spec connects directly to:

• 01-ui-ux-web-app.md

• 02-auth.md

• 04-free-plan-rate-limits-and-gateway.md

• 05-portal-backend-control-plane.md

• 06-data-model-and-durable-state.md

The API key layer sits between:

• the user-facing Portal product surface, and

• the backend gateway / request enforcement layer

So this spec should be read together with both the UI/UX spec and the gateway/control-plane specs.

---

16. Working Summary

Portal V1 API keys should be:

• simple to create

• reveal-once

• easy to revoke

• clearly owned by a user or organization

• product-facing rather than router-facing

The recommended V1 approach is:

• let users manage keys in a clean hosted product UI

• use Unkey for key verification / rate-limit support

• keep ownership, metadata, and durable product logic inside the Portal backend and Portal database

In one sentence:

Portal V1 API keys are product-owned hosted API credentials with simple create/revoke UX, reveal-once secret handling, and clear separation between user-facing key management and backend router infrastructure.