Management Services API (0.0.0)

Create a new user and send an Auth0 invitation email.

The user is created in PENDING status. An async job sends the Auth0 invitation. Once the user accepts the invite and logs in, their status transitions to ACTIVE.

Authorization (requires mgmt:write:users scope):

• Admin Users: Invites user to their tenant (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Invites user to specified tenant. X-Tenant-ID header required.

Returns 409 if a user with the same email already exists in this tenant.

Resend the Auth0 invitation email for a user in PENDING or INVITE_FAILED status.

Deletes any existing Auth0 invitation and creates a new one with a fresh expiration. Updates invited_at timestamp.

Authorization (requires mgmt:write:users scope):

• Admin Users: Can resend invites for users in their tenant. X-Tenant-ID header ignored.
• Operations Users: Can resend invites for users in any tenant. X-Tenant-ID header required.

Returns 404 if user not found. Returns 409 if user is not in PENDING or INVITE_FAILED status.

Retrieve a single tenant by slug.

Authorization: a tenant user reading their own tenant (mgmt:read:tenant), or an Operations User reading any tenant (mgmt:read:tenants_mgmt). Holding the first scope is not enough to read someone else's tenant: the handler compares the caller's organization to the tenant's and returns 403 otherwise.

Returns 404 if not found.

Records a customer's interest and tells Operations about it. Nothing is provisioned and no contract exists until Operations records one.

Accepted rather than created: the answer a customer is waiting for is a conversation with sales, not a resource. Submitting a second time is allowed - a request with more detail than the last one is worth having, and refusing it would leave the customer with no way to correct a mistake.

Writes directly to the Stripe Customer backing this tenant's subscription — there is no local copy.

Cancels at period end rather than immediately: the customer has paid for the period already, and access should run to the end of it.

The local row is not deleted. subscriptions_tenant_unique means one subscription per tenant, so the row has to survive for the tenant to ever subscribe again; Stripe's customer.subscription.deleted webhook moves it to 'canceled' when the period actually closes. Until then the subscription stays 'active' with cancelAtPeriodEnd set, which is what the customer sees.

Idempotent: cancelling an already-cancelling subscription returns the same state rather than erroring.

Changing the plan tier within the same billing interval takes effect immediately: Stripe prorates the difference and invoices it against the saved payment method. Capacity the customer asked for today should not wait a month.

Changing the billing interval - monthly to yearly or back - is scheduled for the end of the current period instead. Doing it immediately would refund part of a month already used and start the new period on an arbitrary date, and no allowance is credited on a mid-cycle change, so the customer would pay the annual price and receive nothing until the year was up. The response carries subscription.pendingChange and no client secret, because nothing is charged today.

Drops a pending billing-interval change, leaving the subscription on what it is already paying for. Only meaningful while pendingChange is set; once the period has turned over the change is the subscription and reversing it is an ordinary change in the other direction.

Creates the Stripe Customer + Subscription server-side (payment_behavior: default_incomplete) and returns a client secret for the frontend to confirm the card directly with Stripe. Card data never passes through our backend.

Append-only audit trail of every token movement for this tenant — grants, expiries, purchases, and job-driven debits from recorded usage events. Default sort: created_at DESC (newest first).

Creates a Stripe PaymentIntent for a one-off token purchase and returns its client secret, so the browser confirms the card directly with Stripe and no card data reaches this service.

Tokens are NOT credited here. The balance moves only once Stripe confirms the charge, when payment_intent.succeeded arrives at the webhook and writes a purchase entry to the ledger. A caller who never confirms, or whose card is declined, leaves no ledger movement at all - which is why this returns an intent rather than a balance.

What tokens cost to buy on top of the plan allotment, so a client can show the price while the customer chooses an amount.

For display only. A purchase is always priced again server-side from the same configuration, so a stale or tampered copy of this cannot change what a card is charged.

Aggregates recorded usage events per user, so a tenant admin can see who spent the organisation's tokens rather than only that the organisation did.

Lifetime totals, for the same reason usage-summary is: usage_events carries no period marker.

Attribution only exists from the point mimic-api began reporting a submitter. Earlier consumption is real and is still counted, in a single entry with no user attached, so the entries continue to sum to the tenant total rather than quietly disagreeing with it.

Token consumption bucketed over time, for the usage chart. Hourly buckets for the 24h range, daily for the rest.

Bucketed on when the work completed rather than when the event was recorded, so a backlog drained after an outage lands on the hours the jobs actually ran. Events that report no completion time fall back to their record time.

Aggregates recorded usage events into per-category totals, so a dashboard can show where a tenant's tokens went rather than only how many are left.

Totals are lifetime, not per billing period: usage_events carries no period marker, and deriving one from the subscription's current period would silently exclude history from before the current plan.

List users within the target tenant.

Authorization (requires mgmt:read:users scope):

• Admin Users: Lists users in their tenant (from JWT org_id). X-Tenant-ID header ignored.
• Operations Users: Lists users in specified tenant. X-Tenant-ID header required.

Default sort: created_at DESC, email ASC (newest first, stable tie-breaker).

Retrieve a single user by ID.

Authorization (requires mgmt:read:users scope):

• Admin Users: Can only read users in their tenant. X-Tenant-ID header ignored.
• Operations Users: Can read users in any tenant. X-Tenant-ID header required.

Returns 404 if user not found or not in target tenant.

Update an existing user's name, role, or status.

Authorization (requires mgmt:write:users scope):

• Admin Users: Can update users in their tenant. X-Tenant-ID header ignored.
• Operations Users: Can update users in any tenant. X-Tenant-ID header required.

Note: Cannot transition status to PENDING or INVITE_FAILED via this endpoint.

Returns 404 if user not found or not in target tenant.

Soft-delete a user (sets status to DEACTIVATED).

Authorization (requires mgmt:write:users scope):

• Admin Users: Can delete users in their tenant. X-Tenant-ID header ignored.
• Operations Users: Can delete users in any tenant. X-Tenant-ID header required.

Idempotent: returns 204 even if already deactivated or not found.

Revokes the user's Auth0 sessions and refresh tokens, so any access token already issued to them stops working at its next silent refresh rather than lasting until it expires on its own.

A support action, not a state change: the user stays active and may log straight back in. To stop someone logging in at all, suspend them instead, which blocks the account and revokes access together.

Authorization (requires mgmt:write:users scope):

• Admin Users: Can sign out users in their tenant. X-Tenant-ID header ignored.
• Operations Users: Can sign out users in any tenant. X-Tenant-ID header required.

Returns 409 for a user who has never logged in, since a pending invitation has no session to revoke.

The Operations log. Newest first.

Cross-tenant by definition, so it carries no tenant header and no slug: the point of the log is to see across tenants, and the scope restricts it to the Operations organization. Narrow it to one tenant with tenantSlug.

Paged on (occurred_at, id) rather than by offset. The log grows continuously, so an offset page shifts under the reader as rows arrive above it.

Scope: mgmt:read:tenants_mgmt, Operations Users only.

Soonest to run out first, because the view exists to answer which renewals are coming up.

Each row carries the organization it belongs to, joined server-side rather than fetched per row - the same N+1 the ops registry had to fix.

One contract per organization. Sending this for an organization that already has one revises those terms; a renegotiation is the same contract on new terms, not a second one.

Recording terms does not provision anything. The tenant's plan, seats and token balance still come from its subscription, which is granted separately - so a contract can be drafted and corrected before any capacity is handed out, and a typo here cannot spend real compute.

Removes the commercial record. The tenant, its users and its subscription are untouched.

Create a new Operations user and send an Auth0 invitation email into the internal Qvyon Operations organization.

Unlike UserInvitesAPI, there is no tenant to target — this always invites into the Operations organization, so no X-Tenant-ID header is accepted.

Authorization: Operations Users only (requires mgmt:write:tenants_mgmt scope). Admin Users receive 403 Forbidden.

Returns 409 if a user with the same email already exists in the Operations organization.

Creating a plan with a key that already exists is a conflict, not an update. Changing one is update, which is the call that knows a price change has to reach Stripe.

The catalogue as Operations has to see it to edit it, which includes the plans no longer offered. The public list hides those, and editing a catalogue through a view that omits part of it is how a retired plan gets recreated under a second key.