> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/cookbooks/platform-admin.md).

# Platform Admin

API workflows for managing account access, models, costs, and agent governance.

Platform Admin cookbooks run account administration through APIs. Use them from an integration, CI/CD job, or internal admin tool.

### Before your first call

| Requirement            | Use it for                                      |
| ---------------------- | ----------------------------------------------- |
| Tenant service URL     | Directing a request to the correct microservice |
| Administrative API key | Authenticating and authorizing the request      |
| Account ID             | Scoping account-level operations                |
| Project or app ID      | Scoping selected agent operations               |

Most Platform Admin tasks use **Identity Hub**. Its QA URL is `https://api-builder-qa.uptiq.dev/identity-hub`.

{% hint style="warning" %}
**Service paths are required.** For example, create a key at `POST https://api-builder-qa.uptiq.dev/identity-hub/api-keys`.
{% endhint %}

### Recommended setup order

1. [Create an account](/cookbooks/platform-admin/give-people-access/create-an-account.md) or identify an existing account.
2. [Create an API key](/cookbooks/platform-admin/programmatic-access/issue-an-api-key.md) for your integration.
3. [Set a credit limit](/cookbooks/platform-admin/cost/cap-account-spending.md) for the account.
4. [Enable a model family](/cookbooks/platform-admin/models/enable-a-model-family.md) and configure its gateway.
5. [Invite a user](/cookbooks/platform-admin/give-people-access/invite-someone.md), [create a team](/cookbooks/platform-admin/give-people-access/create-a-team.md), and automate ongoing operations.

### Service map

| Area                                | Microservice  | QA base URL                                      | First endpoint                  |
| ----------------------------------- | ------------- | ------------------------------------------------ | ------------------------------- |
| Identity, access, models, and costs | Identity Hub  | `https://api-builder-qa.uptiq.dev/identity-hub`  | `POST /accounts`                |
| Agent controls and evidence         | Agent Builder | `https://api-builder-qa.uptiq.dev/agent-builder` | `POST /agents/executions/abort` |

Read the [authentication reference](https://gitlab.com/uptiq-inc-enterprise/development/documentation/platform-docs-repo/-/tree/main/api-references/qa/getting-started/authentication.md) before integrating. Header names differ across services.

### Find a task

Choose the outcome you need, then open its procedure.

{% tabs %}
{% tab title="Identity and access" %}

| Task                                                                                               | Description                                                   |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [Add a business unit](/cookbooks/platform-admin/give-people-access/create-an-account.md)           | Add a business unit with separate access and credit controls. |
| [Onboard a person](/cookbooks/platform-admin/give-people-access/invite-someone.md)                 | Create a user record and assign their first roles.            |
| [Update a person's access](/cookbooks/platform-admin/give-people-access/change-someones-access.md) | Add or remove roles for an existing user.                     |
| [Offboard a person](/cookbooks/platform-admin/give-people-access/remove-someones-access.md)        | Remove access and complete required follow-up actions.        |
| [Organize people into a team](/cookbooks/platform-admin/give-people-access/create-a-team.md)       | Group people and set their operating scope.                   |
| [Change a team's members](/cookbooks/platform-admin/give-people-access/manage-team-membership.md)  | Add or remove people from a team.                             |
| [Set team ownership](/cookbooks/platform-admin/give-people-access/give-a-team-access.md)           | Grant a team access to specific agents and apps.              |
| {% endtab %}                                                                                       |                                                               |

{% tab title="API keys" %}

| Task                                                                                             | Description                                        |
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| [Connect an integration](/cookbooks/platform-admin/programmatic-access/issue-an-api-key.md)      | Create a restricted credential for an integration. |
| [Respond to an exposed key](/cookbooks/platform-admin/programmatic-access/replace-an-api-key.md) | Retire a leaked or stale credential.               |
| {% endtab %}                                                                                     |                                                    |

{% tab title="Models" %}

| Task                                                                                           | Description                                                    |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Make models available](/cookbooks/platform-admin/models/enable-a-model-family.md)             | Enable a model family and assign its tiers.                    |
| [Use your provider credentials](/cookbooks/platform-admin/models/use-your-own-provider-key.md) | Authenticate a provider using your organization’s credentials. |
| [Verify a model before use](/cookbooks/platform-admin/models/check-model-availability.md)      | Confirm a model works before an agent uses it.                 |
| {% endtab %}                                                                                   |                                                                |

{% tab title="Usage and limits" %}

| Task                                                                                    | Description                                         |
| --------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [Prevent account overspend](/cookbooks/platform-admin/cost/cap-account-spending.md)     | Set a hard limit for account credit usage.          |
| [Get notified about usage](/cookbooks/platform-admin/cost/get-alerted-before-a-cap.md)  | Email account admins when usage passes a threshold. |
| [Understand account spending](/cookbooks/platform-admin/cost/find-what-used-credits.md) | Break down usage by app, agent, model, and feature. |
| {% endtab %}                                                                            |                                                     |

{% tab title="Agent operations" %}

| Task                                                                                                         | Description                                            |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
| [Stop work that's in progress](/cookbooks/platform-admin/agents-and-evidence/stop-an-agent.md)               | Interrupt an execution, agent, project, or account.    |
| [Check connector permissions](/cookbooks/platform-admin/agents-and-evidence/review-what-agents-can-reach.md) | Identify connector access through the supported route. |
| [Troubleshoot an agent run](/cookbooks/platform-admin/agents-and-evidence/investigate-a-run.md)              | Fetch a conversation or execution record.              |
| [Check administrative activity](/cookbooks/platform-admin/agents-and-evidence/show-who-changed-what.md)      | Access administrative audit records through MCP.       |
| [Collect activity records](/cookbooks/platform-admin/agents-and-evidence/export-activity-for-review.md)      | Pull source datasets and assemble an export.           |
| {% endtab %}                                                                                                 |                                                        |
| {% endtabs %}                                                                                                |                                                        |

{% hint style="warning" %}
**QA environment:** Use the QA service URL shown for each endpoint. Use the matching production tenant URL for shipped work.
{% endhint %}

### Shared request headers

Most recipes here are Identity Hub calls, authenticated with an account API key:

* `x-platform-key: YOUR_API_KEY` — an account key holding the permission the workflow needs
* `accountid` is **not** required; an account key resolves its own account

**Four recipes need a user session token instead** — `authorization: Bearer <token>`, which expires one hour after issue:

| Recipe                                                                                         | Why the account key fails                                                   |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Stop an agent](/cookbooks/platform-admin/agents-and-evidence/stop-an-agent.md)                | Agent Builder never reads the key — same `404` as sending no credential     |
| [Investigate an agent run](/cookbooks/platform-admin/agents-and-evidence/investigate-a-run.md) | as above                                                                    |
| [Set a credit limit](/cookbooks/platform-admin/cost/cap-account-spending.md)                   | endpoint resolves the calling *user*; a key has none → `404 USER_NOT_FOUND` |
| [Create a usage alert](/cookbooks/platform-admin/cost/get-alerted-before-a-cap.md)             | as above                                                                    |

Because that token is short-lived, none of these four can run unattended on a schedule today.

See the [authentication reference](https://gitlab.com/uptiq-inc-enterprise/development/documentation/platform-docs-repo/-/tree/main/api-references/qa/getting-started/authentication.md) for the full credential matrix and the per-service header spellings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.uptiq.ai/cookbooks/platform-admin.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.