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

# Partner API

> Provision and manage OneCLI organizations on behalf of your customers with the Partner API.

The Partner API is for resellers, agencies, and platforms that manage OneCLI for their customers. A **partner** sits one level above organizations. You create organizations for your customers, hand them ready-to-use credentials and a claim link, and let each customer take ownership when they're ready.

<Note>
  Partner accounts are provisioned by the OneCLI team; there is no self-serve signup yet. Once your partner account exists, you receive a Partner API key and can manage everything below programmatically.
</Note>

## Authentication

The Partner API accepts two credentials:

* **Partner API key**: a key prefixed `oc_partner_`, sent as a Bearer token. Use this for programmatic access.
* **Partner portal session**: the dashboard session of a logged-in partner member. Use this from the portal UI.

For API calls, pass your Partner API key in the `Authorization` header:

```bash theme={null}
curl https://api.onecli.sh/v1/partner/orgs \
  -H "Authorization: Bearer oc_partner_your_key_here"
```

<Warning>
  Treat your `oc_partner_` key like a root credential. It can create organizations and mint the org, project, and agent tokens for every customer you manage. Store it in a secret manager and never commit it.
</Warning>

## How it works

```mermaid theme={null}
flowchart LR
  P[Partner] -->|POST /partner/orgs| O[New organization]
  O -->|org, project, agent tokens + claim link| C[Customer]
  C -->|opens claim link, signs in| Owned[Customer owns the org]
```

You provision an organization, the customer starts using it immediately with the tokens you pass them, and ownership transfers to the customer when they open the claim link.

<Steps>
  <Step title="Create an organization">
    Call `POST /partner/orgs` with a name. The response returns everything needed to run and to claim the organization.
  </Step>

  <Step title="Hand off the credentials and claim link">
    Give the org token, project token, and agent token to your customer (or wire them into your own tooling), and send them the `claimUrl`.
  </Step>

  <Step title="Customer claims ownership">
    The customer opens the claim link, signs in to OneCLI, and becomes the owner of the organization. Each organization has one claim link at a time.
  </Step>

  <Step title="Manage shared secrets and the org lifecycle">
    Optionally share partner-level secrets that every organization inherits, rotate tokens, reissue claim links, or add projects, all through the Partner API.
  </Step>
</Steps>

## What you receive when you create an organization

`POST /partner/orgs` returns one ready-to-use organization with four credentials and a claim link:

| Field            | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `organizationId` | ID of the new organization.                                                      |
| `projectId`      | ID of its default project.                                                       |
| `orgApiKey`      | Organization-scoped API key (`oc_org_…`) for managing the org across projects.   |
| `projectApiKey`  | Project-scoped API key (`oc_…`) for the default project.                         |
| `agentToken`     | Access token for the default agent; route traffic through the gateway with this. |
| `claimUrl`       | The link your customer opens to claim ownership of the organization.             |

```json theme={null}
{
  "organizationId": "org_8f3c1a9b",
  "projectId": "proj_2d7e4f10",
  "orgApiKey": "oc_org_1b9d…",
  "projectApiKey": "oc_7a2f…",
  "agentToken": "aoc_4e8c…",
  "claimUrl": "https://onecli.sh/claim?token=9a229f90b2ec5bf0…"
}
```

<Warning>
  These tokens are shown **once**, in this response only. They are never returned again, so store them when you create the organization. If they're lost, call `POST /partner/orgs/{orgId}/rotate-tokens` to mint new ones.
</Warning>

## Before an organization is claimed

A newly created organization is **unclaimed** until a customer opens its claim link. While it's unclaimed:

* **LLM calls work**: your customer (or your tooling) can start using agents against Anthropic, OpenAI, and other LLM hosts right away.
* **Other external calls are paused**: any non-LLM request through the gateway returns a `claim_required` response containing the claim link, so the customer is prompted to finish setup.

Once claimed, the organization behaves like any other OneCLI organization and the customer is its owner.

## Partner-managed secrets

Secrets you create with `POST /partner/secrets` are **inherited by every organization you manage**. They're the lowest-priority credential tier: when a host matches at more than one level, project secrets override organization secrets, which override partner secrets.

This lets you set a shared credential (say a fallback LLM key) once, and have it apply across all your customers' organizations without provisioning it per org. Customers see inherited secrets as read-only.

A customer can stop inheriting your secrets at any time by detaching their organization (`POST /org/partner/detach`). Detaching keeps the organization, and its attribution to you, but stops applying partner secrets.

## Spend budgets

You can cap how much each organization spends on a partner LLM key. Set a budget on a key for one organization with `POST /partner/orgs/{orgId}/secrets/{secretId}/budget`, choosing a limit and a period:

* **`monthly`** resets on the 1st of each month (UTC).
* **`total`** is a one-time lifetime cap.

When an organization's spend on that key reaches the limit, the gateway stops using the key for that organization and returns a `budget_exceeded` response with a link to add a key. Because a customer's own project or organization key overrides the partner key, adding one lets them keep working. Spend is tracked per organization, so the same key can carry a different budget for each customer.

Budgets apply to metered LLM keys (Anthropic today). `GET /partner/orgs/{orgId}/budgets` returns an organization's budgets, each with its spend so far this period.

## Managing organizations

| Action                           | Endpoint                                             |
| -------------------------------- | ---------------------------------------------------- |
| List your organizations          | `GET /partner/orgs`                                  |
| Inspect one organization         | `GET /partner/orgs/{orgId}`                          |
| Reissue a claim link             | `POST /partner/orgs/{orgId}/claim-link`              |
| Rotate org + project tokens      | `POST /partner/orgs/{orgId}/rotate-tokens`           |
| Delete an unclaimed organization | `DELETE /partner/orgs/{orgId}`                       |
| Add or remove projects           | `GET`/`POST`/`DELETE /partner/orgs/{orgId}/projects` |

<Note>
  Reissuing claim links, rotating tokens, deleting an organization, and managing projects are only allowed while an organization is **unclaimed**. After a customer claims it, the organization is theirs to manage.
</Note>

## Team members

Bring teammates into your partner portal with `POST /partner/members`. Each member signs in with their own email. There are three roles:

* **Owner**: one per partner, set when the partner is created. It can't be granted, changed, or removed.
* **Admin**: manages members and everything else in the portal.
* **Member**: works with organizations, secrets, and projects, but can't manage members or change budgets.

Adding members, changing roles, removing members, and setting budgets all require the owner or an admin.

## Endpoint reference

Browse the full request and response details under these groups in the API Reference:

* **Partner Organizations**: create, list, inspect, delete, reissue claim links, rotate tokens.
* **Partner Projects**: add and remove projects on an unclaimed organization.
* **Partner Secrets**: manage credentials inherited across every organization.
* **Partner Budgets**: set, list, and remove per-organization spend caps on your LLM keys.
* **Partner Members**: add, list, re-role, and remove people in your partner portal.
* **Organization Partner**: check partner status and detach (called by the customer's organization, not by the partner).