Partner API: server-side enrollment key creation (POST /enrollment-keys)

[obsidiangroup]

Use case

MSP tools and integrators that automate device onboarding need a way to generate enrollment tokens server-side without a full user session. Today the only option is POST /api/v1/enrollment-keys, which requires Authorization: Bearer <JWT> — meaning a user must authenticate (including any MFA step-up) before a token can be issued.

For server-to-server automation this is a blocking gap. The Partner API already has the right auth model (X-API-Key with service principal scopes) and RLS pattern for this kind of integration.

Proposed addition

Add POST /enrollment-keys to the Partner API (under /api/v1/partner-api/), gated by a new enrollment-keys:write scope on the calling service principal.

Request:

POST /api/v1/partner-api/enrollment-keys
X-API-Key: brz_sp_...

{
  "orgId": "uuid",
  "siteId": "uuid",     // optional — scopes the key to a specific site
  "name": "string",
  "maxUsage": 1,        // default 1
  "ttlMinutes": 60      // default 60
}

Behavior mirrors the existing user-facing endpoint:

• Raw key returned only on creation; stored value is always the hash
• Org access gated by principal.accessibleOrgIds
• siteId ownership validated against the specified org

The new enrollment-keys:write scope is opt-in — not included in any default scope set — so existing service principal keys are unaffected.

Why the Partner API and not a new endpoint?

The Partner API already handles the service-principal auth, RLS context, and org-scoping logic that this feature needs. Adding it there keeps the pattern consistent and avoids introducing a second auth scheme for automation use cases.

Implementation

I have a working implementation ready as a PR from a fork if the team is open to it. The change is four files:

• New route handler — apps/api/src/routes/partnerApi/enrollmentKeys.ts
• Scope constant — enrollment-keys:write added to PARTNER_SERVICE_PRINCIPAL_SCOPES in partnerServicePrincipalScopes.ts
• Route registration — one line in apps/api/src/routes/partnerApi/index.ts
• Database migration — breeze_valid_partner_service_principal_scopes (the SQL function backing the partner_service_principals_scopes_check constraint) must be updated to include the new scope value. Without this, any attempt to add enrollment-keys:write to an existing service principal is rejected at the database level. The migration uses CREATE OR REPLACE FUNCTION so it is safe to apply to an existing installation without dropping the constraint or any data.

Happy to adjust scope naming, parameter defaults, or anything else to fit the project's conventions.

[farfromexact]

The proposal is close; the highest-risk part is the token lifecycle rather than the route itself. The API key scope, organization ownership, site ownership, and RLS boundary should all be checked before creating the key, with an explicit rejection for a site outside the requested organization.

For the generated enrollment key, I would require a bounded TTL and maxUsage, hash it at rest, return the raw value only in the creation response, and make consumption atomic so concurrent requests cannot exceed maxUsage. Rate limits, audit events, and an idempotency strategy would also be useful. Avoid putting the raw key in URLs or logs, and make sure error payloads never echo it.

The implementation should specify the 201 response schema and errors for invalid scope, expired keys, exhausted keys, and cross-organization access. A migration test plus concurrency tests around maxUsage would give confidence that the database function and application allowlist are updated consistently.

[obsidiangroup]

Thanks for the detailed review — we've addressed the feedback before submitting.

• Audit events — enrollment_key.create is now written after every successful creation via createAuditLogAsync, with actorType: api_key, via: partner_api, and partnerId in the details payload. This is consistent with the user-facing route.

• Idempotency — Added X-Idempotency-Key header support backed by Redis (24 h TTL). The first request returns 201 with the raw key and caches the safe record. Replays within the window return 200 with the metadata and idempotencyReplay: true; the raw key is intentionally absent on replay since it cannot be reconstructed. Degrades gracefully when Redis is unavailable (cache miss → new key created rather than blocking).

• Rate limiting — Already enforced by partnerApiAuthMiddleware via a per-principalId:keyId Redis rate limiter. Returns 429 with X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers. No additional per-endpoint limiting was needed.

• Atomic maxUsage enforcement — Our endpoint only creates keys; maxUsage enforcement on consumption (when agents enroll) is handled by the existing Breeze enrollment infrastructure and applies equally to partner-created keys. We're not introducing a new consumption path.

• No raw key in URLs or logs — Confirmed. The key is only in the 201 response body and never logged, echoed in errors, or included in replay responses.

• Migration test / concurrency tests — We're happy to add these. We didn't find existing migration-level or concurrency test patterns in the repo to follow — if you can point us to an example test file, we'll add both a sync test for the DB function / TS enum and a concurrency test around maxUsage consumption before merge.

[ToddHebebrand]

Reviewed — and yes, this is a gap we want to close. Server-side minting for provisioning pipelines is a legitimate need the session-bound UI flow doesn't serve, and a scoped service-principal permission is the right mechanism for it.

Full review is on the PR (#2826): the structure is right and the migration is clean, but there are five things to fix before merge — the biggest being that the new write scope currently lands in the default scope set (so it isn't opt-in as described), and that the TTL path skips the partner-configured expiry cap the user-facing routes enforce. Details with file references are in the review.

Once those land I'm happy to merge this — thanks for pairing the proposal with a working implementation.

[obsidiangroup]

All 5 must-fix items addressed — commit 47f3dc6 fixes. The nice to have, I'll look into next.