---
title: "Provision a partner-linked AgentTax account"
method: POST
path: "/api/v1/partner/provision"
tags: ["Partners"]
---

# Provision a partner-linked AgentTax account

`POST /api/v1/partner/provision`

## Request

- Base URL: `https://www.agenttax.io`
- URL: `https://www.agenttax.io/api/v1/partner/provision`
- Auth: API key in header `X-API-Key`

Creates a linked AgentTax account on behalf of a partner-tenant user and returns a scoped API key. **Idempotent on `(partner_id, external_id)`** — repeat calls return the existing account without rotating credentials.

**Auth:** Partner provisioning key (`ptx_live_…`) sent as `X-API-Key` or `Authorization: Bearer`.

**Rate limit:** 600/min per partner key.

## Request body

- PartnerProvisionRequest
  - `external_id` string, required: Partner-side stable identifier for the user. Idempotency key — repeat calls with the same `external_id` return the existing account without rotating credentials.
  - `email` string, email
  - `display_name` string

## Response `200`

Account already provisioned. `api_key` and `claim_url` are NOT returned — those are first-call only.

- PartnerProvisionResponse
  - `agenttax_account_id` string, required
  - `partner_user_id` string, required
  - `api_key` string: Returned ONLY on first provision (HTTP 201). Subsequent calls with the same `external_id` return 200 without `api_key`. Store securely — cannot be retrieved later, only rotated.
  - `claim_url` string, uri: User-facing claim link. Allows the end-user to take over the account directly with AgentTax. Returned only on first provision.
  - `claim_expires_at` string, date-time
  - `already_provisioned` boolean, required: true on repeat calls (HTTP 200), false on first provision (HTTP 201).
  - `claimed` boolean: true if the user has claimed the account directly with AgentTax.

## Other responses

- `201`: New account created. `api_key` is returned ONCE — store securely.
- `400`: Missing or invalid `external_id` / `email`.
- `401`: Invalid partner provisioning key.
- `429`: Rate limited (600/min per partner key).
- `500`: Provisioning failed (DB or downstream).

---

[API](https://skmtc.dev/agenttax/apis/agenttax-api.md) · [All operations](https://skmtc.dev/agenttax/apis/agenttax-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agenttax/apis/agenttax-api/revisions/c4af8147c0cb?raw)