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