sharang
4c46d673fb
Replaces the M5.1-skeleton handler set with the M4.2 spec from
IMPLEMENTATION_PLAN.md:
Endpoints (authoritative shape in openapi.yaml):
POST /v1/tenants
GET /v1/tenants/{id}
GET /v1/tenants/by-slug/{slug}
POST /v1/tenants/{id}/activate
POST /v1/tenants/{id}/cancel
GET /v1/entitlements?tenant_id=...
GET /v1/catalog
POST /v1/catalog/request
POST /v1/catalog/trial-request
POST /v1/api-keys returns plaintext ONCE
GET /v1/api-keys?tenant_id=...
DELETE /v1/api-keys/{id}
POST /v1/internal/api-keys/verify always 200; valid: bool
POST /v1/audit
GET /v1/audit?{tenant_id,product,actor_id,action,since,until,limit,cursor}
Architecture:
internal/store/store.go Store interface (CRUD + audit + ping)
internal/store/memory.go in-process impl, used when DATABASE_URL
is empty (seed acme tenant, no migrations)
internal/store/postgres.go pgxpool impl against the M4.1 schema
internal/server/server.go router + healthz/readyz
internal/server/{tenants,catalog,apikeys,audit}.go
per-concern handlers (≤250 LoC each)
internal/server/helpers.go writeJSON/writeError/error mapping/log mw
openapi.yaml 3.1 spec; openapi_test.go is the contract gate
API keys:
Plaintext format 'bp_<22-char base64>'. Prefix bp_<8> stored for UI.
Hash is argon2id(salt, time=1, mem=64MB, threads=4, len=32) encoded as
'argon2id|<salt-b64>|<hash-b64>'. Format-tagged so we can rotate
parameters without re-keying. Verify is constant-time.
Store selection:
cmd/server picks Postgres when DATABASE_URL is set, otherwise Memory.
Both implementations are exercised by the same eachStore test harness —
parity is enforced.
Audit:
Every state-changing endpoint emits via s.emitAudit() (fire-and-forget).
audit_log uses ON DELETE SET NULL on tenant_id so forensic history
outlives tenant deletes (per M4.1 schema).
Routing constraint:
Go 1.22 ServeMux can't disambiguate /v1/tenants/{id}/products from
/v1/tenants/by-slug/{slug=products}. Per-tenant subresources moved to
query-param top-level paths: /v1/entitlements?tenant_id=… and
/v1/api-keys?tenant_id=….
Tests:
Every endpoint exercised against both Memory and Postgres via the
eachStore harness. Includes happy paths, validation errors, conflicts,
404s, auto-audit-emit assertion. testcontainers-go for the postgres
harness; gated by -short.
TestOpenAPISpec is the contract gate: every documented operation must
resolve against the router. (kin-openapi v0.138.0.)
Refs: M4.2
486 lines
16 KiB
YAML
486 lines
16 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.
|
|
|
|
This API is not yet authenticated — M4.3 adds Keycloak JWT validation.
|
|
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.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/TenantCreate" } }
|
|
responses:
|
|
"201":
|
|
description: Created.
|
|
content:
|
|
application/json: { schema: { $ref: "#/components/schemas/Tenant" } }
|
|
"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/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:
|
|
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:
|
|
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 }
|
|
|
|
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 }
|