sharangandSharang Parnerkar
ce75ed04c2
Implements the model-B2 membership authority (ratified compliance auth design) and inbound token verification.
- GET /v1/users/{id}/memberships: Keycloak supplies user->tenant links + org_roles (attribute projection until the realm migrates to Organizations); registered tenants override status/plan/products from registry tables (source: registry|keycloak). Closes the M5.2-deferred org_roles stub.
- New internal/authn: OIDC discovery + JWKS verification (go-oidc/v3), audience tenant-registry. /healthz + /readyz stay PUBLIC_EXPLICIT; all other routes INTERNAL_SERVICE_ONLY. AUTH_ENABLED=true refuses to start on incomplete config (fail-closed); false (dev default) keeps current behavior.
- Full suite green incl. postgres testcontainers; openapi.yaml updated (contract test passes).
Activation is a separate step (Auth-5): requires the orca-infra env merge and a portal service token (portal currently calls with no auth).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Sharang Parnerkar <30073382+mighty840@users.noreply.github.com>
Reviewed-on: #14
597 lines
20 KiB
YAML
597 lines
20 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Tenant Registry
|
|
version: 0.1.0
|
|
description: |
|
|
Internal platform API. Owns the multi-tenant glue: tenants, projects,
|
|
product entitlements, API keys, audit log. See
|
|
`PLATFORM_ARCHITECTURE.md §5c` for the schema, and
|
|
`PRODUCT_INTEGRATION_SPEC.md §8.4` for the audit shape.
|
|
|
|
Auth (RBAC Phase 1): with AUTH_ENABLED=true every route except
|
|
/healthz and /readyz requires a Keycloak-issued bearer token whose
|
|
audience contains AUTH_EXPECTED_AUDIENCE (INTERNAL_SERVICE_ONLY
|
|
posture). With AUTH_ENABLED=false (dev default) the API is open.
|
|
contact:
|
|
email: oncall@breakpilot.com
|
|
license:
|
|
name: Proprietary
|
|
servers:
|
|
- url: http://localhost:8090
|
|
description: Local dev
|
|
- url: https://tenant-registry.stage.breakpilot.com
|
|
description: Stage
|
|
- url: https://tenant-registry.breakpilot.com
|
|
description: Production
|
|
|
|
paths:
|
|
/healthz:
|
|
get:
|
|
summary: Liveness probe
|
|
responses:
|
|
"200":
|
|
description: Always returns ok.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties: { status: { type: string, example: ok } }
|
|
|
|
/readyz:
|
|
get:
|
|
summary: Readiness probe — pings the store.
|
|
responses:
|
|
"200":
|
|
description: Store reachable.
|
|
"503":
|
|
description: Store unreachable.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Error" } }
|
|
|
|
/v1/tenants:
|
|
post:
|
|
summary: Create a tenant.
|
|
description: |
|
|
Creates the tenant row, and if `admin_email` is provided, also
|
|
creates a Keycloak organization + invites the user as IT_ADMIN.
|
|
Keycloak failures DO NOT roll the tenant back — they emit a
|
|
`keycloak.provision_failed` audit event so the operator can resend
|
|
the invite from the KC admin UI.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/TenantCreate" } }
|
|
responses:
|
|
"201":
|
|
description: Created. `invite_url` is non-empty when an
|
|
`admin_email` was passed and Keycloak provisioning succeeded.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/TenantCreated" } }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"409": { $ref: "#/components/responses/Conflict" }
|
|
|
|
/v1/tenants/{id}:
|
|
get:
|
|
summary: Get tenant by id.
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: Found.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Tenant" } }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/tenants/by-slug/{slug}:
|
|
get:
|
|
summary: Get tenant by slug.
|
|
parameters:
|
|
- in: path
|
|
name: slug
|
|
required: true
|
|
schema: { type: string, pattern: '^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$' }
|
|
responses:
|
|
"200":
|
|
description: Found.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Tenant" } }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/tenants/{id}/activate:
|
|
post:
|
|
summary: Move tenant to status=active.
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/TenantActivate" } }
|
|
responses:
|
|
"200":
|
|
description: Updated.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Tenant" } }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/tenants/{id}/cancel:
|
|
post:
|
|
summary: Move tenant to status=frozen.
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/TenantCancel" } }
|
|
responses:
|
|
"200":
|
|
description: Updated.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Tenant" } }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/entitlements:
|
|
get:
|
|
summary: List product entitlements for a tenant.
|
|
parameters:
|
|
- in: query
|
|
name: tenant_id
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: List response.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
items:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/TenantProduct" }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/catalog:
|
|
get:
|
|
summary: List the products available for any tenant to request.
|
|
responses:
|
|
"200":
|
|
description: Catalog.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
items:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/CatalogEntry" }
|
|
|
|
/v1/catalog/request:
|
|
post:
|
|
summary: Request a product (creates an audit event; sales follows up).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/CatalogRequest" } }
|
|
responses:
|
|
"202":
|
|
description: Accepted.
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/catalog/trial-request:
|
|
post:
|
|
summary: Self-serve a 14-day trial.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/CatalogRequest" } }
|
|
responses:
|
|
"201":
|
|
description: Trial entitlement created.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/TenantProduct" } }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/api-keys:
|
|
get:
|
|
summary: List API keys for a tenant.
|
|
parameters:
|
|
- in: query
|
|
name: tenant_id
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"200":
|
|
description: List response. The plaintext key is NOT returned;
|
|
use the create endpoint and store the value immediately.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
items:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/APIKey" }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
post:
|
|
summary: Create an API key. The plaintext is returned ONCE.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/APIKeyCreate" } }
|
|
responses:
|
|
"201":
|
|
description: Created. The plaintext field is shown only here.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/APIKeyCreated" } }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/api-keys/{id}:
|
|
delete:
|
|
summary: Revoke an API key (sets revoked_at).
|
|
parameters:
|
|
- in: path
|
|
name: id
|
|
required: true
|
|
schema: { type: string, format: uuid }
|
|
responses:
|
|
"204":
|
|
description: Revoked.
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/users/{id}/memberships:
|
|
get:
|
|
summary: Resolve which tenants a user belongs to (membership authority).
|
|
description: |
|
|
The B2 membership-authority endpoint (ratified compliance auth
|
|
design). Product backends call this with the JWT `sub` instead of
|
|
trusting token claims or client-supplied headers. Keycloak supplies
|
|
the user→tenant links and org_roles; where the tenant is registered
|
|
here, tenant_status / plan / products are overridden from registry
|
|
tables (source: "registry"), otherwise the Keycloak attribute
|
|
projection is returned as-is (source: "keycloak").
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: Keycloak user id (the JWT `sub`).
|
|
schema: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Memberships (possibly empty) for the user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [user_id, memberships]
|
|
properties:
|
|
user_id: { type: string }
|
|
memberships:
|
|
type: array
|
|
items:
|
|
allOf:
|
|
- $ref: "#/components/schemas/Claims"
|
|
- type: object
|
|
required: [source]
|
|
properties:
|
|
source: { type: string, enum: [registry, keycloak] }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
"503":
|
|
description: Keycloak unreachable — membership cannot be resolved.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Error" } }
|
|
|
|
/v1/internal/keycloak/claims:
|
|
post:
|
|
summary: Resolve the up-to-date claim bundle for a user/tenant.
|
|
description: |
|
|
Called by Keycloak's protocol mapper at token issuance (or by
|
|
any operator on demand) to fetch the current tenant_id /
|
|
tenant_slug / org_roles / products / plan / tenant_status
|
|
claims. Lookup tries tenant_id, then tenant_slug, then
|
|
user_attrs.tenant_id, then user_attrs.tenant_slug.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
tenant_id: { type: string, format: uuid }
|
|
tenant_slug: { type: string }
|
|
user_attrs:
|
|
type: object
|
|
additionalProperties: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Resolved claim bundle.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Claims" } }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
"404": { $ref: "#/components/responses/NotFound" }
|
|
|
|
/v1/internal/api-keys/verify:
|
|
post:
|
|
summary: Verify an API key. Used by headless products. Returns
|
|
200 with valid=false on any failure (never 401).
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [key]
|
|
properties:
|
|
key: { type: string }
|
|
responses:
|
|
"200":
|
|
description: Verification result.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/APIKeyVerify" } }
|
|
|
|
/v1/audit:
|
|
post:
|
|
summary: Append an audit event.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/AuditAppend" } }
|
|
responses:
|
|
"201":
|
|
description: Created.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/AuditEvent" } }
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
get:
|
|
summary: List audit events (paginated, cursor-based).
|
|
parameters:
|
|
- in: query
|
|
name: tenant_id
|
|
schema: { type: string, format: uuid }
|
|
- in: query
|
|
name: product
|
|
schema: { type: string }
|
|
- in: query
|
|
name: actor_id
|
|
schema: { type: string }
|
|
- in: query
|
|
name: action
|
|
schema: { type: string }
|
|
- in: query
|
|
name: since
|
|
schema: { type: string, format: date-time }
|
|
- in: query
|
|
name: until
|
|
schema: { type: string, format: date-time }
|
|
- in: query
|
|
name: limit
|
|
schema: { type: integer, minimum: 1, maximum: 500 }
|
|
- in: query
|
|
name: cursor
|
|
schema: { type: integer, format: int64 }
|
|
responses:
|
|
"200":
|
|
description: Paginated response. next_cursor is omitted when
|
|
there are no more pages.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
items:
|
|
type: array
|
|
items: { $ref: "#/components/schemas/AuditEvent" }
|
|
next_cursor:
|
|
type: integer
|
|
format: int64
|
|
"400": { $ref: "#/components/responses/BadRequest" }
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
Keycloak-issued token (client_credentials for services). Enforced
|
|
on all non-health routes when AUTH_ENABLED=true.
|
|
|
|
responses:
|
|
BadRequest:
|
|
description: Input failed validation.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Error" } }
|
|
NotFound:
|
|
description: Resource does not exist.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Error" } }
|
|
Conflict:
|
|
description: Resource already exists / unique violation.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Error" } }
|
|
|
|
schemas:
|
|
Claims:
|
|
type: object
|
|
required: [tenant_id, tenant_slug, plan, tenant_status]
|
|
properties:
|
|
tenant_id: { type: string, format: uuid }
|
|
tenant_slug: { type: string }
|
|
org_roles: { type: array, items: { type: string } }
|
|
products: { type: array, items: { type: string } }
|
|
plan: { type: string }
|
|
tenant_status: { type: string, enum: [demo, trial, active, frozen, archived] }
|
|
|
|
Error:
|
|
type: object
|
|
required: [error]
|
|
properties:
|
|
error: { type: string, example: invalid_input }
|
|
message: { type: string }
|
|
|
|
Tenant:
|
|
type: object
|
|
required: [id, slug, name, status, kind, plan, created_at, updated_at]
|
|
properties:
|
|
id: { type: string, format: uuid }
|
|
slug: { type: string }
|
|
name: { type: string }
|
|
status: { type: string, enum: [demo, trial, active, frozen, archived] }
|
|
kind: { type: string, enum: [customer, demo] }
|
|
plan: { type: string }
|
|
erp_customer_id: { type: string }
|
|
stripe_cust_id: { type: string }
|
|
trial_ends_at: { type: string, format: date-time, nullable: true }
|
|
contract_start: { type: string, format: date, nullable: true }
|
|
contract_end: { type: string, format: date, nullable: true }
|
|
sales_owner: { type: string }
|
|
created_at: { type: string, format: date-time }
|
|
updated_at: { type: string, format: date-time }
|
|
|
|
TenantCreate:
|
|
type: object
|
|
required: [slug, name]
|
|
properties:
|
|
slug: { type: string, pattern: '^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$' }
|
|
name: { type: string, minLength: 1, maxLength: 255 }
|
|
plan: { type: string, default: starter }
|
|
kind: { type: string, enum: [customer, demo], default: customer }
|
|
sales_owner: { type: string }
|
|
admin_email: { type: string, format: email, description: "IT_ADMIN to invite via Keycloak" }
|
|
admin_name: { type: string }
|
|
|
|
TenantCreated:
|
|
type: object
|
|
required: [tenant]
|
|
properties:
|
|
tenant: { $ref: "#/components/schemas/Tenant" }
|
|
invite_url: { type: string, description: "KC action-token URL — present only when admin_email was set and KC provisioning succeeded" }
|
|
|
|
TenantActivate:
|
|
type: object
|
|
properties:
|
|
plan: { type: string }
|
|
contract_start: { type: string, format: date }
|
|
contract_end: { type: string, format: date }
|
|
erp_customer_id: { type: string }
|
|
|
|
TenantCancel:
|
|
type: object
|
|
properties:
|
|
reason: { type: string }
|
|
at_period_end: { type: boolean }
|
|
|
|
TenantProduct:
|
|
type: object
|
|
required: [tenant_id, product, enabled, config, created_at, updated_at]
|
|
properties:
|
|
tenant_id: { type: string, format: uuid }
|
|
product: { type: string }
|
|
enabled: { type: boolean }
|
|
config: { type: object, additionalProperties: true }
|
|
expires_at: { type: string, format: date-time, nullable: true }
|
|
created_at: { type: string, format: date-time }
|
|
updated_at: { type: string, format: date-time }
|
|
|
|
CatalogEntry:
|
|
type: object
|
|
required: [key, name, description, plans_required, supports_trial]
|
|
properties:
|
|
key: { type: string }
|
|
name: { type: string }
|
|
description: { type: string }
|
|
plans_required: { type: array, items: { type: string } }
|
|
demo_url: { type: string }
|
|
supports_trial: { type: boolean }
|
|
|
|
CatalogRequest:
|
|
type: object
|
|
required: [tenant_id, product]
|
|
properties:
|
|
tenant_id: { type: string, format: uuid }
|
|
product: { type: string }
|
|
|
|
APIKey:
|
|
type: object
|
|
required: [id, tenant_id, name, scopes, prefix, created_at]
|
|
properties:
|
|
id: { type: string, format: uuid }
|
|
tenant_id: { type: string, format: uuid }
|
|
product: { type: string }
|
|
name: { type: string }
|
|
scopes: { type: array, items: { type: string } }
|
|
prefix: { type: string }
|
|
created_by: { type: string }
|
|
last_used_at: { type: string, format: date-time, nullable: true }
|
|
revoked_at: { type: string, format: date-time, nullable: true }
|
|
created_at: { type: string, format: date-time }
|
|
|
|
APIKeyCreate:
|
|
type: object
|
|
required: [tenant_id, name]
|
|
properties:
|
|
tenant_id: { type: string, format: uuid }
|
|
name: { type: string, maxLength: 100 }
|
|
product: { type: string }
|
|
scopes: { type: array, items: { type: string } }
|
|
created_by: { type: string }
|
|
|
|
APIKeyCreated:
|
|
type: object
|
|
required: [api_key, plaintext, warning]
|
|
properties:
|
|
api_key: { $ref: "#/components/schemas/APIKey" }
|
|
plaintext: { type: string }
|
|
warning: { type: string }
|
|
|
|
APIKeyVerify:
|
|
type: object
|
|
required: [valid]
|
|
properties:
|
|
valid: { type: boolean }
|
|
tenant_id: { type: string, format: uuid }
|
|
product: { type: string }
|
|
scopes: { type: array, items: { type: string } }
|
|
|
|
AuditAppend:
|
|
type: object
|
|
required: [action]
|
|
properties:
|
|
tenant_id: { type: string, format: uuid }
|
|
project_id: { type: string, format: uuid }
|
|
actor_id: { type: string }
|
|
actor_name: { type: string }
|
|
actor_type: { type: string }
|
|
action: { type: string }
|
|
target_id: { type: string }
|
|
target_type: { type: string }
|
|
target_name: { type: string }
|
|
product: { type: string }
|
|
metadata: { type: object, additionalProperties: true }
|
|
|
|
AuditEvent:
|
|
allOf:
|
|
- $ref: "#/components/schemas/AuditAppend"
|
|
- type: object
|
|
required: [id, created_at]
|
|
properties:
|
|
id: { type: integer, format: int64 }
|
|
source_ip: { type: string }
|
|
user_agent: { type: string }
|
|
created_at: { type: string, format: date-time }
|