API keys and webhooks

This is the technical part of the settings. It brings together 2 independent blocks: API keys on one side, webhooks and their delivery log on the other. Each depends on a different plan entitlement, so one can be open while the other is locked.

#What the screen shows

• One card per API key: name, state, the start of the key, scopes, daily quota, last use and creation date.
• The creation window offers 8 scopes: mint:batch, mint:single, products:read, products:status, transfers:create, sellout:write, webhooks:read, webhooks:write. It arrives pre-filled with mint:batch, a quota of 1000 per day and a validity of 365 days.
• The webhook creation window offers 23 event types, kept identical to the list the server accepts.
• The delivery log: timestamp, target subscription, type, state, response code, attempt number and duration. Unfolding a row shows the content sent and the response received.

#What you can do here

• Create a key by choosing a name, a brand, scopes, a daily quota and a validity period.
• Copy the key secret. It is shown once only, at creation.
• Revoke an active key, after confirmation.
• Create a webhook subscription by giving an address and ticking the events you want.
• Filter the log, then retry a failed delivery.

#What controls access

• The API key block depends on the api_access entitlement, the webhook block on the webhooks entitlement, which is a separate one.
• When a key is created, the server checks in order that the plan is active, that the api_access entitlement is present, then that the key quota is not reached.
• The database keeps only a fingerprint of the secret and a 12 character prefix. A lost secret cannot be recovered.
• With no period given, a key expires after 365 days.
• The key creation button stays disabled while the name, the brand or at least one scope is missing.
• The webhook creation button stays disabled while no brand is chosen, while the address is shorter than 10 characters, or while no event is ticked.
• The revoke button only appears on active keys, the retry button only on failed deliveries.
• A delivery counts as delivered when its response code sits between 200 and 299.
• The log fetches the last 100 deliveries per subscription, while the server accepts 200 per call. The key list likewise stops at the last 100.

#What the screen refuses

• Without the matching entitlement, the block is greyed out and covered by a padlock stating that the feature is locked.
• A webhook address that does not use HTTPS is refused: "Webhook URL must use HTTPS".
• Retrying a successful delivery is refused: "Cannot retry a successful delivery".
• Retrying a delivery whose content was not kept is refused: "This delivery has no stored payload and cannot be retried; trigger a fresh event instead."
• Revoking a key warns that it cannot be undone and that every request in flight with that key will fail immediately.