# Управление командой (Team API)

Team API позволяет автоматизировать управление участниками команды: создавать учётные записи сотрудников, приглашать существующих пользователей, менять роли и лимиты расходов — всё по мастер-ключу командного аккаунта.

Базовый путь: `https://routerai.ru/api/v1/team`

## Аутентификация

Используется **мастер-ключ команды** — тот же тип ключа, что и для [управления API-ключами](/docs/guides/overview/authentication):

1. Переключитесь в командный аккаунт **под администратором команды**
2. Перейдите в [Настройки → Мастер-ключи](https://routerai.ru/settings/provisioning_keys)
3. Создайте мастер-ключ и сохраните его

Важно про доступ:

- Мастер-ключ должен быть создан **в контексте команды**. Мастер-ключ личного аккаунта получит `403`.
- Управлять командой может только ключ, **созданный администратором** команды. Мастер-ключ, созданный обычным участником (роль `member`), предназначен для управления его собственными API-ключами и к Team API не допускается — вернётся `403`. Если участника позже понизили с админа до `member`, его ранее созданные ключи тоже перестают управлять командой.

```bash
curl -H "Authorization: Bearer YOUR_TEAM_MASTER_KEY" \
  https://routerai.ru/api/v1/team
```

## Создание учётной записи сотрудника

`POST /api/v1/team/members` создаёт подтверждённую учётную запись и сразу добавляет её в команду — сотруднику не нужно регистрироваться и принимать приглашение.

```bash
curl -X POST https://routerai.ru/api/v1/team/members \
  -H "Authorization: Bearer YOUR_TEAM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "employee@example.com",
    "role": "member",
    "monthly_spending_limit": 5000
  }'
```

Ответ содержит одноразовую ссылку установки пароля (действует 6 часов):

```json
{
  "data": {
    "id": 42,
    "user_id": 1001,
    "email": "employee@example.com",
    "role": "member",
    "active": true,
    "is_owner": false,
    "monthly_spending_limit": "5000.0",
    "monthly_spending": "0.0",
    "created_at": "2026-07-07T12:00:00.000Z"
  },
  "password_setup_url": "https://routerai.ru/users/password/edit?reset_password_token=..."
}
```

Варианты выдачи доступа:

| Параметры                        | Результат                                                        |
| -------------------------------- | ---------------------------------------------------------------- |
| (по умолчанию)                   | В ответе `password_setup_url` — доставьте сотруднику сами         |
| `"send_email": true`             | Плюс письмо со ссылкой установки пароля от платформы              |
| `"password": "..."`              | Пароль задан сразу, ссылки нет                                    |
| `"password" + "send_email": true`| Письмо с логином и паролем открытым текстом (учитывайте риски)    |

Если email уже зарегистрирован, вернётся `409` — используйте приглашения.

## Приглашение существующего пользователя

`POST /api/v1/team/invitations` создаёт приглашение, которое пользователь принимает под своим аккаунтом (email должен совпадать). Действует 7 дней.

```bash
curl -X POST https://routerai.ru/api/v1/team/invitations \
  -H "Authorization: Bearer YOUR_TEAM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "role": "member", "send_email": true}'
```

В ответе будет `invite_url` — ссылка принятия; без `send_email: true` письмо не отправляется, доставьте ссылку сами.

## Управление участниками

```bash
# Список активных участников
curl -H "Authorization: Bearer YOUR_TEAM_MASTER_KEY" \
  https://routerai.ru/api/v1/team/members

# Смена роли и лимита (0 — без лимита)
curl -X PATCH https://routerai.ru/api/v1/team/members/42 \
  -H "Authorization: Bearer YOUR_TEAM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin", "monthly_spending_limit": 0}'

# Удаление из команды (мягкое — членство деактивируется)
curl -X DELETE https://routerai.ru/api/v1/team/members/42 \
  -H "Authorization: Bearer YOUR_TEAM_MASTER_KEY"

# Возврат деактивированного участника
curl -X PATCH https://routerai.ru/api/v1/team/members/42 \
  -H "Authorization: Bearer YOUR_TEAM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'
```

Ограничения:

- Владельца команды нельзя понизить или удалить (лимит менять можно)
- Последнего активного администратора нельзя понизить или удалить

Полное описание эндпоинтов — в [справочнике API](/docs/reference).