> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Management API Keys

> Create scoped management keys for Phaseo control-plane APIs.

Management API keys are server-side credentials for Phaseo's control plane:
credits, activity, workspace administration, key management, presets, settings,
and guardrails. They are not for sending inference requests.

Create them with `phaseo management-keys create --name <name> --template read-only --json` in the
[Phaseo CLI](https://phaseo.app/docs/v1/guides/integrations/phaseo-cli.md), or in **Dashboard → Settings →
Management Keys**. A secret is shown once; store it in your secret manager.

## Key types

| Credential | Use it for | Controls |
| - | - | - |
| Gateway API key | Model and generation requests | Routing policy, budgets, limits, and attached guardrails |
| Management API key | Control-plane requests | Explicit management capabilities and workspace-role checks |
| OAuth access token | Delegated control-plane access | The approved OAuth scopes and workspace-role checks |

Management routes accept only `phaseo_v1_mk_<kid>_<secret>`. Gateway API keys
use `phaseo_v1_sk_<kid>_<secret>` and are inference-only; they cannot access
control-plane endpoints.

Use management keys only from server-side code:

```http theme={null}
Authorization: Bearer phaseo_v1_mk_<kid>_<secret>
```

The production base URL is:

```text theme={null}
https://api.phaseo.app/v1
```

## Choose an access level

The dashboard offers explicit templates. Each template expands to the listed
capabilities when the key is created; Phaseo never stores a wildcard such as
`all`. A key therefore cannot gain a newly introduced permission implicitly.

| Template | Grants |
| - | - |
| **Read** | Every current `*:read` management capability |
| **Write** | Every current `*:read` and `*:write` capability; no delete access |
| **All** | Every current read, write, and delete management capability |

## Capability reference

Use an access template for common cases. Use explicit capabilities when an
integration needs a smaller, purpose-built grant.

| Area | Read | Write | Delete |
| - | - | - | - |
| Identity and catalogue | `me:read`, `models:read`, `providers:read`, `pricing:read` | — | — |
| Usage and observability | `credits:read`, `activity:read`, `analytics:read`, `generations:read`, `feedback:read` | `feedback:write` | — |
| Workspaces | `workspaces:read` | `workspaces:write` | `workspaces:delete` |
| Gateway API keys | `keys:read` | `keys:write` | `keys:delete` |
| Management API keys | `management_keys:read` | `management_keys:write` | `management_keys:delete` |
| Presets | `presets:read` | `presets:write` | `presets:delete` |
| Settings | `settings:read` | `settings:write` | — |
| Provider credentials | `provider_credentials:read` | `provider_credentials:write` | `provider_credentials:delete` |
| Private models | `private_models:read` | `private_models:write` | `private_models:delete` |
| Guardrails | `guardrails:read` | `guardrails:write` | `guardrails:delete` |
| Budgets | `budgets:read` | `budgets:write` | `budgets:delete` |
| Rate limits | `rate_limits:read` | `rate_limits:write` | `rate_limits:delete` |
| Classifiers | `classifiers:read` | `classifiers:write` | `classifiers:delete` |
| Spend rules | `spend_rules:read` | `spend_rules:write` | `spend_rules:delete` |
| OAuth clients | `oauth_clients:read` | `oauth_clients:write` | `oauth_clients:delete` |

`Write` templates include the matching read capabilities so an integration can
inspect a resource before updating it. `All` includes delete capabilities; use
it only for trusted administrative automation.

## Scopes and workspace roles

A scope is necessary but not sufficient. Phaseo also verifies the key or OAuth
principal belongs to the requested workspace and has the required workspace
role. A scoped key cannot use a capability to access another workspace or
bypass ownership and administrator checks.

For example, `keys:write` authorizes key-management operations, while the
workspace role check determines whether the caller may manage keys in that
workspace.

## Guardrails are different

Guardrails apply to **gateway API keys** and govern inference traffic: routing
restrictions, budgets, prompt-injection handling, and sensitive-information
rules. Management-key scopes govern which administration APIs a credential may
call. They are complementary controls, not substitutes.

See [Roll out guardrails on API keys](https://phaseo.app/docs/v1/cookbook/guardrails-for-api-keys.md)
for an inference-key guardrail rollout.

## Security and rotation

* Keep management keys out of browsers, desktop logs, source control, and chat.
* Use one purpose-built key per integration and prefer the narrowest template.
* Give keys an expiry where the integration does not need indefinite access.
* Pause or delete unused keys immediately.
* Rotate a leaked key before investigating the incident further.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.