Авторизация
Как устроен ключ API, как его получить, передать и сменить.
Каждый запрос к API подписывается ключом. Ключ принадлежит одному мерчанту и одному контуру. Других способов входа нет.
Как выглядит ключ
ak_test_<16 знаков>_<секрет>
ak_live_<16 знаков>_<секрет>- Открытая часть:
ak_test_илиak_live_и шестнадцать знаков, строчные латинские буквы и цифры. Это не секрет: по ней ключ называют в консоли и в переписке с поддержкой. - Секрет: 43 знака после второго подчёркивания. Его знаете только вы. На нашей стороне хранится только хеш секрета, поэтому потерянный ключ восстановить нельзя.
Передаётся всегда ключ целиком.
Как получить ключ
Ключ выдаёт администратор в консоли Plutera: карточка мерчанта, вкладка «Ключи API». При выдаче выбирают контур и, если нужно, срок действия.
- Ключ целиком показывается один раз, сразу после выдачи. Потом его не видит никто, включая администратора.
- У мерчанта может быть до 10 ключей одновременно, считая оба контура. Выключенные и просроченные ключи место занимают, отозванные нет.
- Ключ можно выдать заранее, пока мерчант ещё не в работе. Принимать запросы ключ начнёт, когда мерчанта активируют и откроют ему контур ключа.
Как передать ключ
Заголовком Authorization со словом Bearer:
GET /api/v1/me HTTP/1.1
Host: api.plutera.io
Authorization: Bearer <ключ>Клиентам, которые умеют только схему Basic: ключ идёт именем пользователя, пароль пустой. В curl это -u "$PLUTERA_API_KEY:". Запись с непустым паролем ключом не считается.
Сессия консоли оператора для API не годится: запрос, с которым пришла её кука, отклоняется.
Состояния ключа
| Состояние | Что значит | Обратимо |
|---|---|---|
| Действует | Запросы принимаются | |
| Выключен | Администратор временно выключил ключ | Да, ключ включают обратно |
| Просрочен | Истёк срок, заданный при выдаче | Нет, нужен новый ключ |
| Отозван | Ключ отозван или заменён перегенерацией | Нет, отзыв окончателен |
Смена ключа без простоя
Перегенерация отзывает прежний ключ и выдаёт новый одним действием: прежний перестаёт приниматься в ту же секунду. Чтобы сменить ключ без простоя:
- Попросите выдать второй ключ.
- Переведите на него все свои серверы.
- Попросите отозвать первый.
Когда ключ не годится
Пока секрет не сошёлся, ответ один и тот же: 401 без причины. Нет ключа, ключ не по форме, такого ключа не существует, секрет не тот: ответ не различает эти случаи намеренно, иначе он подсказывал бы постороннему, какие ключи существуют.
Когда секрет сошёлся, ответ называет причину в поле details.rule. Если причин несколько, называется одна, в таком порядке: отзыв, срок, выключатель, затем состояние мерчанта, затем закрытый контур.
Все отказы входа с примерами: каталог отказов.