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

# Administration

> Create and manage user accounts.

export const Throttling = () => {
  return <Warning>
      This endpoint is rate limited; if you receive a <code>429</code> response, pause for the
      backoff time required by the <code>Retry-After</code> header before making another request.
    </Warning>;
};

export const apiEndpoint = 'api.agentfirst.dev';

export const companyName = 'Agent First';

<Info>
  See also the <Link href="endpoints/reference/users">API reference</Link> for more detail.
</Info>

## Usage

**{companyName}'s** administration service lets you support your whitelabel customers. The service
has a RESTful interface that accepts `GET`, `POST`, `PATCH`, and `DELETE` requests at
**https\://‍{apiEndpoint}/users**.

<Throttling />

### New customers

You can provision a user by specifying their email address and, optionally, the API credits to
preload their account with:

```shell theme={null}
curl -X POST 'https://api.agentfirst.dev/users' \
-H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
  "email": "user@example.com",
  "credits": 1000
}'
```

The user's secret API token will be returned, along with their normalized email address and any
credits:

```json theme={null}
{
  "email": "user@example.com",
  "token": "a1-0dF6qKHYD7SNU5kAtjOmwHpH3iFgpylA",
  "credits": 1000
}
```

Here are the provisioning request keys and values:

| Key       | Required | Value                                                                                                                                                     |
| :-------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`   | ✅        | The email address of the user to create an account for; the address is case insensitive and can be up to 255 characters, regardless of character encoding |
| `credits` |          | The number of API credits to preload the account with                                                                                                     |

Here are the response keys and values:

| Key       | Value                                                       |
| :-------- | :---------------------------------------------------------- |
| `email`   | The email address of the new account as recorded by the API |
| `token`   | The bearer token issued to the account for authentication   |
| `credits` | The number of initial credits granted to the account        |

### Customer deactivation

Disable an account with the associated email address:

```shell theme={null}
curl -X DELETE 'https://api.agentfirst.dev/users' \
-H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
-H 'Content-Type: application/json' \
-d '{ "email": "user@example.com" }'
```

The API will confirm that account no longer has credits:

```json theme={null}
{
  "email": "user@example.com",
  "credits": 0
}
```

This is the deprovisioning request key and value:

| Key     | Required | Value                                                                        |
| :------ | :------- | :--------------------------------------------------------------------------- |
| `email` | ✅        | The (case-insensitive) email address of the user whose account to deactivate |

These are the response keys and values:

| Key       | Value                                          |
| :-------- | :--------------------------------------------- |
| `email`   | The email address of the deactivated account   |
| `credits` | The zeroed-out credits as confirmed by the API |