Перейти к содержимому
CalabДокументация

Регистрация клиента

Создать OAuth-клиент в настройках пространства, выбрать тип, redirect URI и scopes, сменить секрет.

Клиент — это запись о вашем приложении в конкретном пространстве: имя, которое увидит пользователь, тип, точные адреса возврата и набор данных профиля. Создаёт его владелец или администратор пространства в приложении Calab.

Перед началом

  • Тариф пространства — Business (или on-prem Enterprise с включённым провайдером). Иначе вкладка заблокирована.
  • Вы — владелец или администратор пространства и вошли локальным аккаунтом (не корпоративной SSO-сессией).
  • Пароль подтверждён не более 5 минут назад. Calab попросит «Подтвердить пароль», если подтверждение устарело.
  • Если в пространстве включён «Обязательный SSO», нужно ещё и свежее (не старше 5 минут) подтверждение корпоративного входа — кнопка «Подтвердить корпоративный вход».

Создание

  1. Откройте Настройки пространства → «OAuth-клиенты» и нажмите «Создать клиент».
  2. Заполните поля:
ПолеЧто указатьОграничения
«Название» (раздел «Приложение»)Имя, которое увидит пользователь на экране согласия1–100 символов
«Тип клиента»«Веб-приложение с сервером», «Нативное приложение» или «Браузерное приложение (SPA)»После создания не меняется
«Redirect URI (по строкам)»Точные адреса, куда Calab вернёт пользователя с code1–10 адресов, без *, #, пробелов и учётных данных в URL
«Разрешённые origins (по строкам)»Только для SPA: origins, с которых браузер вызывает /token, /userinfo, /revokeДо 10, только https://host[:port], без пути
«Доступ к профилю»openid (всегда) и по желанию profile, email—
«Разрешить продолжение доступа»Выдавать ли refresh tokenПользователь всё равно решает сам на экране согласия
  1. Сохраните. Calab покажет client_id (вида calab_client_…), а для веб-приложения с сервером — ещё и секрет (calab_os_…).

Правила для redirect URI

  • Сравнение побайтовое: путь, регистр, завершающий / и query-строка должны совпадать с зарегистрированными. Префиксов и масок нет.
  • Веб и SPA: только https://.
  • Нативные приложения дополнительно могут использовать:
    • loopback http://127.0.0.1:{port}/… или http://[::1]:{port}/… — порт может меняться от запуска к запуску (RFC 8252), всё остальное должно совпадать; localhost не принимается;
    • собственную схему в обратной доменной записи с путём, например com.example.crm:/oauth/callback.

Лимиты

  • До 20 активных клиентов в пространстве (409, reason: "PLAN_LIMIT").
  • У конфиденциального клиента одновременно не больше двух действующих секретов.

Изменение клиента

Правка имени ничего не ломает: уже выданные доступы продолжают работать, а при следующем входе пользователь увидит новое имя на экране согласия (тихий вход prompt=none вернёт consent_required, пока человек не подтвердит новое имя).

Изменение redirect URI, origins, scopes или «Разрешить продолжение доступа» — это изменение безопасности: Calab отзывает все выданные доступы этого клиента и прерывает незавершённые входы. Пользователям придётся войти заново.

Смена секрета

«Сменить секрет» выдаёт новый секрет (показывается один раз) и:

  • по умолчанию оставляет прежний секрет действующим ещё 10 минут — успейте обновить конфигурацию сервера;
  • с флажком «Сразу отозвать прежний секрет» прежний секрет перестаёт работать немедленно.

Если действующих секретов уже два, сначала дождитесь истечения прежнего или используйте «Сразу отозвать прежний секрет».

Удаление

«Удалить» отключает клиент: его секреты и все выданные доступы отзываются, /authorize и /token начинают отвечать ошибкой. client_id не переиспользуется.

API управления

Те же действия доступны по REST — это API приложения Calab, и он требует сессию человека (владельца или администратора) с теми же условиями, что выше. Токены ботов и OAuth-токены здесь не принимаются, а запросы, меняющие данные, принимаются только с origin самого Calab. Поэтому для автоматизации используйте интерфейс; таблица — для понимания модели.

МетодПутьЧто делает
GET/api/workspaces/{workspace}/oauth/clientsСписок клиентов пространства
POST/api/workspaces/{workspace}/oauth/clientsСоздать клиент → 201 {client, secretOnce}
GET/api/workspaces/{workspace}/oauth/clients/{client}Один клиент (по id записи или clientId)
PATCH/api/workspaces/{workspace}/oauth/clients/{client}Полный снимок редактируемых полей + ожидаемая version
DELETE/api/workspaces/{workspace}/oauth/clients/{client}Отключить клиент → 204
POST/api/workspaces/{workspace}/oauth/clients/{client}/rotate-secretСменить секрет {revokeOld} → {client, secretOnce, oldSecretValidUntil}

Тело создания (protojson, поля в lowerCamelCase):

JSON
{
  "name": "Acme CRM",
  "type": "OAUTH_CLIENT_TYPE_CONFIDENTIAL_WEB",
  "redirectUris": ["https://crm.example.com/auth/calab/callback"],
  "allowedOrigins": [],
  "scopes": ["openid", "profile", "email"],
  "refreshEnabled": true
}

Ответ 201:

JSON
{
  "client": {
    "id": "0192a0f1-5c3e-7b21-9d4a-6e8f0a1b2c3d",
    "workspaceId": "0192a000-0000-7000-8000-0000000000aa",
    "clientId": "calab_client_e07JrYTVpGfRYJ0pQaF6yzkME6S9W856DgsKNWOKvgE",
    "name": "Acme CRM",
    "type": "OAUTH_CLIENT_TYPE_CONFIDENTIAL_WEB",
    "redirectUris": ["https://crm.example.com/auth/calab/callback"],
    "scopes": ["email", "openid", "profile"],
    "refreshEnabled": true,
    "version": "1",
    "createdAt": "2026-10-14T09:00:00Z"
  },
  "secretOnce": "calab_os_VWMV4RGIRsisgKhdE7ohFW_QoAdNWS4n9GkM3Ty1kb4"
}

PATCH принимает {version, name, redirectUris, allowedOrigins, scopes, refreshEnabled} целиком. Если version устарела (кто-то изменил клиент раньше), ответ — 409 с reason: "IDENTITY_CONFIG_CHANGED": перечитайте клиент и повторите.

Дальше