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

# Getting Started

> Create and manage sub-custodians with the Reseller API.

# Reseller API

The Reseller API lets approved resellers create and manage sub-custodians through Portal. Use it to create a sub-custodian, view its environments, suspend access, and create environment-scoped Portal API keys for that sub-custodian.

## Authentication

Create a Reseller API key in the Portal dashboard from the **Reseller** section. Reseller API keys are environment-agnostic and authenticate the reseller itself.

Send the key as a bearer token on every request:

```bash theme={null}
Authorization: Bearer <RESELLER_API_KEY>
```

<Note>
  A reseller can only access sub-custodians that belong to that reseller.
</Note>

## Create a sub-custodian

Create a sub-custodian with an initial user. Portal creates Development and Production environments for the sub-custodian, enables Portal backup and session tokens, and sends the initial user an onboarding invite.

```bash theme={null}
curl --request POST \
  --url https://api.portalhq.io/api/v3/resellers/custodians \
  --header 'Authorization: Bearer <RESELLER_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "custodian": {
      "name": "Acme Payments"
    },
    "user": {
      "email": "admin@acmepayments.com",
      "firstName": "Avery",
      "lastName": "Stone"
    }
  }'
```

Sub-custodians created through the Reseller API are active, non-reseller custodians on the Start-Up plan with Portal backup and session tokens enabled.

## List sub-custodians

```bash theme={null}
curl --request GET \
  --url https://api.portalhq.io/api/v3/resellers/custodians \
  --header 'Authorization: Bearer <RESELLER_API_KEY>'
```

The response includes each sub-custodian's environments, users, billing plan, billing status, and Portal API key metadata.

## List sub-custodian environments

Use the sub-custodian ID from the create or list response.

```bash theme={null}
curl --request GET \
  --url https://api.portalhq.io/api/v3/resellers/custodians/<CUSTODIAN_ID>/environments \
  --header 'Authorization: Bearer <RESELLER_API_KEY>'
```

## Create a sub-custodian Portal API key

Sub-custodian Portal API keys are scoped to one sub-custodian environment. The raw API key value is only returned when the key is created.

```bash theme={null}
curl --request POST \
  --url https://api.portalhq.io/api/v3/resellers/custodians/<CUSTODIAN_ID>/environments/<ENVIRONMENT_ID>/api-keys \
  --header 'Authorization: Bearer <RESELLER_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Production API key"
  }'
```

## Suspend a sub-custodian

Suspending a sub-custodian blocks that custodian's Portal dashboard users, Portal API keys, client API keys, client session tokens, and service-authenticated requests.

```bash theme={null}
curl --request PUT \
  --url https://api.portalhq.io/api/v3/resellers/custodians/<CUSTODIAN_ID>/suspend \
  --header 'Authorization: Bearer <RESELLER_API_KEY>'
```