05.02 Merchant API Keys

Статус: черновик для обсуждения

1. Назначение документа

Этот документ описывает merchant API keys для новой системы.

Merchant API key используется merchant-ом для подписи API requests.

В MVP API key нужен для:

deposit API;
future withdrawal API;
request authentication;
request signature validation;
merchant identification.

2. Основной принцип

API key является secret value.

Это не public key / secret pair.

Merchant получает secret и использует его для подписи requests.

Secret показывается только один раз при создании / rotation.

После закрытия one-time secret screen secret нельзя посмотреть повторно.

Система должна хранить key securely и не раскрывать secret повторно.

3. Scope API key

API key создается на уровне:

text

Merchant

API key не создается на brand.

Один merchant API key может использоваться для всех brands этого merchant-а.

В deposit request merchant передает:

request data;
signature, сформированную с использованием API key secret;
brandId;
paymentMethodId.

Система валидирует, что:

API key относится к merchant;
brandId принадлежит этому merchant;
paymentMethodId доступен этому merchant.

4. Кто может создавать API keys

API key может создать merchant user с permission в context merchant.

Если merchant user имеет доступ к merchant group и permission manage API keys, он может создавать API keys для любого merchant внутри этой group.

Platform user с permission также может управлять API keys merchant-а, если это разрешено access model.

5. Один active key на merchant

Для одного merchant может быть только один active API key.

Одновременно несколько active API keys для одного merchant не допускаются.

Это упрощает:

request validation;
key rotation;
security investigation;
support;
access management.

API key label/name в MVP не нужен.

Причина: один merchant имеет один active key для всего Merchant API, поэтому отдельное название key не дает продуктовой пользы.

6. API key statuses

API key должен иметь status.

Минимальные statuses:

text

ACTIVE
REVOKED
EXPIRED

7. Expiration

API key не имеет обязательного expiration date.

Key работает, пока его не revoke.

Обычный active API key не истекает автоматически по календарной дате.

Status EXPIRED используется для старого key после завершения rotation grace period.

8. Rotation

Merchant user с permission может выполнить key rotation.

При rotation:

Создается новый API key secret.
Новый secret становится primary/active для новых requests.
Старый secret продолжает работать в течение выбранного grace period.
После grace period старый secret перестает работать.

Доступные grace periods:

1 hour;
3 hours;
12 hours;
24 hours.

Grace period нужен, чтобы merchant успел обновить integration без downtime.

Если merchant уже имеет active key и user создает новый key, это всегда считается rotation.

Rotation требует confirmation modal and OTP code.

OTP code нужен для подтверждения sensitive security action.

OTP code берется из user authenticator app 2FA.

Email notification при API key rotation в MVP не требуется.

После окончания grace period старый key автоматически становится:

text

EXPIRED

9. Revoke

При revoke API key должен перестать работать сразу.

Revoke не имеет grace period.

Revoke требует confirmation modal and OTP code.

OTP code берется из user authenticator app 2FA.

Email notification при API key revoke в MVP не требуется.

Если API key был revoked:

новые requests с этим key не принимаются;
merchant получает authentication/signature error;
event записывается в audit log.

10. UI fields

Back Office должен показывать API key metadata.

Минимально:

status;
masked key preview, например последние 4 символа;
created at;
created by;
last used at;
rotated at;
revoked at;
revoked by;
active rotation grace period, если rotation активна;
grace period ends at, если применимо.

API key label/name в MVP не отображается и не настраивается.

Secret value не должен постоянно отображаться в UI.

Secret показывается только один раз после создания / rotation.

API key usage history в MVP не нужен.

Для MVP достаточно metadata:

last used at;
status;
rotation/revoke metadata.

11. API key permissions

В MVP API key не имеет отдельного набора permissions.

Один merchant API key дает доступ к merchant API для:

deposits;
withdrawals в будущем.

Доступ контролируется:

merchant ownership;
request signature;
brandId validation;
paymentMethodId validation;
API endpoint rules.

12. Audit log

Все действия с API keys должны попадать в audit log.

Audit log должен фиксировать:

key created;
key rotated;
old key grace period started;
old key grace period ended;
key revoked;
failed request because of invalid/revoked key, если это нужно для security audit;
actor;
timestamp;
merchant context.

Audit log не должен раскрывать secret value.

13. Security notes

API key secret является sensitive data.

Нельзя показывать secret:

в audit log;
в transaction details;
в webhook payload;
в exports;
в error messages;
в screenshots/logs, если этого можно избежать.

Если key нужно показывать в UI после создания, UI должен явно предупредить user, что secret будет показан только один раз.

Sensitive actions должны требовать OTP confirmation:

rotate API key;
revoke API key.

Email notifications для API key rotate/revoke в MVP не отправляются.

14. Acceptance Criteria

Merchant API Keys считаются согласованными для MVP, если:

API key является secret value для подписи request.
API key не является public/secret pair.
API key создается на merchant.
API key не создается на brand.
Merchant user с permission может создать API key в context merchant.
Merchant group user с permission может создать API key для merchants внутри group.
Для одного merchant может быть только один active API key.
API key label/name не нужен в MVP.
API key имеет statuses ACTIVE, REVOKED, EXPIRED.
API key работает пока не revoke.
Secret показывается только один раз при создании / rotation.
UI показывает masked key preview.
UI показывает created by, created at, last used at.
Rotation поддерживает grace period 1h, 3h, 12h, 24h.
Если active key уже существует, создание нового key считается rotation.
При rotation старый key работает только выбранный grace period.
После grace period старый key автоматически становится EXPIRED.
Rotation требует confirmation modal and OTP code.
Rotation OTP берется из authenticator app 2FA.
При revoke key перестает работать сразу.
Revoke требует confirmation modal and OTP code.
Revoke OTP берется из authenticator app 2FA.
Email notification по API key rotate/revoke не отправляется в MVP.
UI показывает last used at, created by, rotated at и другую metadata.
API key usage history не входит в MVP.
API key не имеет отдельного permission set.
Один API key используется для deposits и future withdrawals.
Все изменения API key пишутся в audit log.
Secret value не попадает в audit log, exports, errors и transaction details.

15. Open Questions

Product open questions отсутствуют.

Technical/security follow-up:

Определить exact request signing algorithm.
Определить exact signature headers.
Определить storage strategy for API key secret.
Определить one-time secret display UX.
Определить behavior для requests during rotation grace period.

05.02 Merchant API Keys ​

1. Назначение документа ​

2. Основной принцип ​

3. Scope API key ​

4. Кто может создавать API keys ​

5. Один active key на merchant ​

6. API key statuses ​

7. Expiration ​

8. Rotation ​

9. Revoke ​

10. UI fields ​

11. API key permissions ​

12. Audit log ​

13. Security notes ​

14. Acceptance Criteria ​

15. Open Questions ​

05.02 Merchant API Keys

1. Назначение документа

2. Основной принцип

3. Scope API key

4. Кто может создавать API keys

5. Один active key на merchant

6. API key statuses

7. Expiration

8. Rotation

9. Revoke

10. UI fields

11. API key permissions

12. Audit log

13. Security notes

14. Acceptance Criteria

15. Open Questions