Skip to content

Subscriptions

Koldan Cloud only

Subscriptions let administrators control what each user can do and how much they can consume. A subscription plan bundles three things together:

  • Quota overrides - storage limits, monthly transcription minutes, summaries, translations, etc.
  • Rate limit overrides - per-operation throttles such as file uploads, transcription jobs, and global requests per minute.
  • Additive permissions - extra permission scopes granted on top of the user's role.

When a field in the plan is left empty, the user inherits the tenant default for that quota or rate limit. This means plans only need to specify what they change.

How Subscriptions Work

flowchart LR
    Admin["Administrator"] -->|assigns plan| US["User Subscription"]
    US -->|references| Plan["Subscription Plan"]
    Plan -->|overrides| Q["Quotas"]
    Plan -->|overrides| RL["Rate Limits"]
    Plan -->|grants| P["Permissions"]
    style Admin fill:#4051b5,color:#fff
    style Plan fill:#43a047,color:#fff
  1. An administrator creates one or more subscription plans (e.g., Free, Pro, Enterprise).
  2. The administrator assigns a plan to a user. Each user can have at most one active subscription.
  3. At runtime, Koldan resolves the user's effective quotas and rate limits by checking - in order:
    • User-level overrides (set directly on the user by an admin)
    • Subscription plan overrides (from the user's active plan)
    • Tenant defaults (the fallback for anything not overridden above)
  4. The plan's additive permissions are merged with the user's role permissions, expanding what the user can access.

Subscription Plans

A plan is identified by a unique slug (e.g., free, pro, enterprise) and has a display name shown in UIs. Plans can be active (available for new assignments) or inactive (deactivated - existing subscribers keep the plan, but no new assignments are allowed).

What a Plan Controls

Category Examples Null Behavior
Quota overrides Storage limit, monthly transcription minutes, monthly summaries, monthly translations, monthly text translations null = inherit tenant default
Rate limit overrides File uploads, transcription jobs, summary executions, translation executions, global requests, user lookups null = inherit tenant default
Additive permissions Any permission scopes (e.g., speech:summaries:execute) Empty = no extra permissions

Plan Lifecycle

State Meaning
Active Can be assigned to users. Visible in the plan listing.
Inactive Deleted. Existing subscribers stay on the plan, but it cannot be assigned to new users.

Administrators manage plans through the Admin Subscriptions API.

User Subscriptions

A user subscription is the link between a user and a plan within a tenant. It tracks:

Field Description
Plan Which subscription plan the user is on
Status ACTIVE - subscription is in effect; CANCELED - subscription has been canceled
Period start When the current subscription period began
Period end Expiration date (if set). null means no expiration
Canceled at Timestamp when the subscription was canceled (if applicable)

What Happens Without a Subscription

Users without a subscription simply use the tenant defaults for all quotas and rate limits, and their permissions are determined solely by their role. No subscription does not mean no access - it means no plan-level overrides.

Manual Assignment

Subscription plans are currently assigned by an administrator - there is no self-service signup or payment automation. Contact your organization's Koldan administrator to request a plan change.

Checking Your Subscription

You can check your current subscription status programmatically via the Subscriptions API:

GET /api/v1/subscription

This returns your active plan details, current period, and status - or 204 No Content if you have no subscription.

Required Scope

The subscriptions:read scope is required to view your subscription. See Roles and Permissions for which roles include this scope.

Browsing Available Plans

To see which plans are available on your tenant:

GET /api/v1/subscription-plans

This returns all active plans with their quota limits, rate limits, and granted permissions. You can also retrieve a specific plan by its slug:

GET /api/v1/subscription-plans/{slug}

Required Scope

The subscriptions:plans:read scope is required. See Roles and Permissions for which roles include this scope.

For full endpoint documentation, see the Subscriptions API reference.