Overview
What the Management API is — a programmatic, token-authenticated interface for administering your organization.
What is the Management API?
The Management API lets your scripts, CI pipelines and FinOps tooling do what an Admin does in the portal — create projects, set guardrails, create and rotate API keys, manage members and pending invites, and read usage, balances, the model catalog and the audit log — with an HTTP call.
https://portal.<domain>/api/v1/mgmtIt is served on the portal host under /api/v1/mgmt — the same address
you open the portal on — while the Inference API stays on
the API host (https://api.<domain>/v1). It is authenticated with a
personal access token
(tf-pat_…) — never with a project API key.
The portal and the Management API act on the same data with the same permission rules, so a change made in one is immediately visible in the other.
Inference API and Management API
Token Factory has two APIs. They follow the same conventions but do different jobs with different credentials — and each credential type is rejected by the other API, so the two never mix.
| Inference API | Management API | |
|---|---|---|
| Serves | Tokens: completions, embeddings, images, speech | Configuration: org, members, projects, keys, usage, billing reads, audit |
| Base URL | https://api.<domain>/v1 | https://portal.<domain>/api/v1/mgmt |
| Credential | Project API key — belongs to a project | Personal access token tf-pat_… — belongs to a person |
| Authenticates | A workload | A human, or the automation standing in for one |
| Audience | Your application | Your Admins and their pipelines |
| Billable | Yes, metered per request | No — the API itself is free (it is rate limited) |
| A failure means | A request did not run | A misconfiguration, or automation that cannot see your organization |
Usage and billing reads are a view of the same usage records the portal and your invoice use. The API computes nothing of its own; if an invoice and an API response ever disagreed, the invoice governs.
Four rules for tokens
Four rules shape how personal access tokens behave. Each has a cost, stated here so you can plan around it.
| # | Rule | Why | What it costs you |
|---|---|---|---|
| 1 | A token is a person's credential, never the org's. | Every audited action is attributable to one person in one org. When someone leaves, their tokens die with their membership — nothing is orphaned. | A departing member's pipelines stop when their membership ends. Re-home automation under someone who stays. |
| 2 | A token can never exceed its creator. | Effective permission is the token's scopes intersected with the creator's live rights, on every request. Privilege escalation by token is impossible. | If the creator is demoted, the token narrows with them. The error says so — see the intersection rule. |
| 3 | One organization per token. | A token is minted inside one org and never resolves outside it — not in a listing, an export or an error. | A user in three orgs needs three tokens for three automations. There is no cross-org view. |
| 4 | Admins mint tokens. | Organization, member, project, usage and audit management is Admin-only, so a Member's token could reach little beyond their own keys. | Developers ask an Admin to mint their CI token — one portal action, once. |
Boundaries
- Not the Inference API. Inference is on the API host
(
https://api.<domain>/v1), management on the portal host under/api/v1/mgmt. A personal access token is rejected at the inference routes, and a project API key is rejected here — both with401 credential_type_mismatchand a message that names the fix. - Billing is read-only. The API tells you what you owe and what you bought; payments, payment methods and credit purchases are handled in the portal. See Billing.
- Tokens are created in the portal. Minting needs re-authentication in the portal, so a leaked token cannot extend its own life. A token can list and revoke its owner's own tokens — see Tokens.
- One organization at a time. No parameter accepts another organization's id, and an object in another org is indistinguishable from one that does not exist (404).
- Automation acts as a person. Every token belongs to a named member, which is what keeps every action attributable.
What you can do with it
Quickstart
Mint a token, read your org, create a project and a key, rotate it.
Personal access tokens
Format, lifecycle, mint policy, and the portal how-to.
Scopes
The 12 scopes, the sensitive class, and the intersection rule.
Automate from CI
Create and rotate a project's key from a pipeline, with no human on the day.
Incident response
Contain a leaked key, a runaway workload or a person in one call each.
Errors
One envelope with a stable code, a human action, and a request_id.
OpenAPI specification
The complete Management API is described by an OpenAPI 3.1 specification,
published in YAML and JSON. Its servers URL already points at the
environment you are reading these docs on.
- OpenAPI specification: YAML · JSON
- Import by URL (Postman, Insomnia, code generators):
/docs/management-api/openapi.json
Use it with Swagger Editor, Postman, Insomnia, Bruno or any OpenAPI-compatible
code generator to explore the API or generate a client: open the link above,
or import the JSON URL into your tool. Every call needs a
personal access token, and
every write needs an Idempotency-Key header.
Resources at a glance
All paths are relative to https://portal.<domain>/api/v1/mgmt. The organization is
implied by the token — there is no /orgs/{org} segment.
| Resource | Paths | Scopes |
|---|---|---|
| Organization | /org | org:read · org:write |
| Members | /members | members:read · members:write |
| Invites | /invites, /invites/{id} | members:read · members:write |
| Projects | /projects | projects:read · projects:write |
| API keys | /projects/{id}/keys, /keys/{id} | keys:read · keys:write |
| Usage | /usage, /usage/export | usage:read |
| Billing | /billing/* | billing:read |
| Audit log | /audit, /audit/export | audit:read |
| Catalog | /catalog/models, /catalog/regions | catalog:read |
| Tokens | /me/tokens | none — any valid token |
Conventions shared by every endpoint
| Convention | Rule |
|---|---|
| Format | JSON in and out, snake_case fields, opaque string ids, ISO-8601 UTC timestamps. |
| Authentication | Authorization: Bearer tf-pat_… on every call — Authentication. |
| Idempotency | Idempotency-Key is required on every POST, PATCH, PUT and DELETE — Idempotency. |
| Pagination | Cursor-based: data, has_more, next_cursor — Pagination. |
| Errors | error.code is stable; error.action tells you the fix — Errors. |
| Rate limits | Per token, with X-RateLimit-* headers on authenticated responses and Retry-After on 429 — Rate limits. |
| Versioning | The path is the version (/api/v1/mgmt); v1 changes are additive only — Versioning. |
| Request ids | Every response carries X-Request-Id (req_…); every error body carries the same id as error.request_id. |
| Response time | Requests running longer than 60 seconds are cut off; exports return at most 10,000 rows per call. |