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

# Account Management

> Create and manage your EldrStream tenant account

# Account Management

***

## Create a tenant

Creates a new EldrStream account. This is the first step for any new user. No authentication is required.

```text theme={null}
POST /v1/tenants
```

### Request body

| Field      | Type   | Required  | Description                                                                                                                            |
| ---------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `tier`     | string | No        | `"free"`, `"pro"`, or `"business"`. Defaults to `"free"`.                                                                              |
| `name`     | string | Paid only | Your organisation or display name. Required for paid tiers.                                                                            |
| `email`    | string | Paid only | Contact email address. Required for paid tiers.                                                                                        |
| `password` | string | Paid only | Account password. Required for paid tiers. Must be at least 8 characters with uppercase, lowercase, a number, and a special character. |
| `webhooks` | array  | No        | Initial webhook configuration. Same format as the [Update Webhooks](./webhooks.md) endpoint.                                           |

#### Password requirements

Passwords must satisfy all of the following:

* Minimum 8 characters
* At least one uppercase letter
* At least one lowercase letter
* At least one digit
* At least one special character (`@`, `#`, `$`, `%`, `^`, `&`, `+`, `=`, `!`)

### Free tier example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{"tier": "free"}'
```

**Response (201 Created)**

```json theme={null}
{
  "tenant_id": "a3f8bc1d2e",
  "tier": "free",
  "name": "sandbox-4a2c9f71",
  "email": "anonymous-4a2c9f71@eldrstream.internal",
  "password": "xK9pQr7mA1@"
}
```

The `password` is only returned once in the free-tier response. Save it immediately.

### Paid tier example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "pro",
    "name": "Acme Corp",
    "email": "dev@acme.io",
    "password": "Secur3P@ss!",
    "webhooks": [
      { "webhook_url": "https://acme.io/hooks/eldrstream", "name": "Production" }
    ]
  }'
```

**Response (201 Created)**

```json theme={null}
{
  "tenant_id": "b7c1e4f2a9",
  "tier": "pro",
  "name": "Acme Corp",
  "email": "dev@acme.io",
  "payment_url": "https://checkout.paystack.com/...",
  "payment_note": "Complete the 100 NGN card verification via the link. Your subscription will be charged at end of month."
}
```

Visit the `payment_url` to complete the one-time card verification step. Your account is activated once the card is tokenised.

### Status codes

| Status            | Meaning                                |
| ----------------- | -------------------------------------- |
| `201 Created`     | Account provisioned successfully       |
| `400 Bad Request` | Validation error (see `message` field) |

***

## Get account info

Returns your current account details, plan tier, and monthly event quota.

```text theme={null}
GET /v1/tenants/me
```

### Authentication

```text theme={null}
Authorization: Bearer <jwt>
```

### Example

```bash theme={null}
curl https://api.eldrstream.com/v1/tenants/me \
  -H "Authorization: Bearer <jwt>"
```

### Response

```json theme={null}
{
  "tenant_id": "a3f8bc1d2e",
  "tenant_name": "Acme Corp",
  "tier": "pro",
  "max_events_per_month": 5000000,
  "email": "dev@acme.io"
}
```

| Field                  | Description                               |
| ---------------------- | ----------------------------------------- |
| `tenant_id`            | Your unique tenant identifier             |
| `tenant_name`          | Your account display name                 |
| `tier`                 | Current plan tier                         |
| `max_events_per_month` | Monthly event quota included in your plan |
| `email`                | Your registered email address             |

***

## Check account status

Returns the activation status of any tenant account. This is a public endpoint useful during onboarding to poll for card verification completion.

```text theme={null}
GET /v1/tenants/{tenantId}/status
```

### Path parameters

| Parameter  | Description            |
| ---------- | ---------------------- |
| `tenantId` | The tenant ID to check |

### Example

```bash theme={null}
curl https://api.eldrstream.com/v1/tenants/b7c1e4f2a9/status
```

### Response

```json theme={null}
{
  "status": "active"
}
```

### Status codes

| Status          | Meaning             |
| --------------- | ------------------- |
| `200 OK`        | Status returned     |
| `404 Not Found` | Tenant ID not found |

***

## Upgrade your plan

Upgrades your account to a higher tier. Downgrades are not supported via API.

```text theme={null}
POST /v1/tenants/upgrade
```

### Authentication

```text theme={null}
Authorization: Bearer <jwt>
```

### Request body

| Field      | Type   | Required       | Description                                                                   |
| ---------- | ------ | -------------- | ----------------------------------------------------------------------------- |
| `tier`     | string | Yes            | Target tier: `"pro"` or `"business"`                                          |
| `email`    | string | Free→paid only | Required when upgrading from a free account                                   |
| `password` | string | Free→paid only | Required when upgrading from a free account. Must meet password requirements. |

### Example

```bash theme={null}
curl -X POST https://api.eldrstream.com/v1/tenants/upgrade \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "pro",
    "email": "dev@acme.io",
    "password": "Secur3P@ss!"
  }'
```

### Response

```json theme={null}
{
  "tenant_id": "a3f8bc1d2e",
  "tier": "pro",
  "included_events": 5000000,
  "payment_status": "paid",
  "message": "Account upgraded to pro successfully"
}
```

If a saved payment method is not available, the response includes a `payment_url` for card verification:

```json theme={null}
{
  "tenant_id": "a3f8bc1d2e",
  "tier": "pro",
  "included_events": 5000000,
  "payment_status": "pending",
  "payment_url": "https://checkout.paystack.com/...",
  "message": "Account upgraded to pro successfully"
}
```

### Status codes

| Status                 | Meaning                                                    |
| ---------------------- | ---------------------------------------------------------- |
| `200 OK`               | Upgrade complete, payment charged                          |
| `202 Accepted`         | Upgrade applied, card verification required                |
| `400 Bad Request`      | Validation error or downgrade attempt                      |
| `402 Payment Required` | Saved card charge failed — update payment method and retry |

***

## Delete account

Permanently deletes your account and all associated data. This action is irreversible.

```text theme={null}
DELETE /v1/tenants
```

### Authentication

```text theme={null}
Authorization: Bearer <jwt>
```

### Example

```bash theme={null}
curl -X DELETE https://api.eldrstream.com/v1/tenants \
  -H "Authorization: Bearer <jwt>"
```

### Response

`204 No Content` on success.

***

## API Keys

See the [API Keys](./api-keys.md) reference for managing your API key.