Authentication
What an API key looks like and how to get it, send it and replace it.
Every API request is signed with a key. A key belongs to one merchant and one environment. There is no other way to sign in.
What a key looks like
ak_test_<16 characters>_<secret>
ak_live_<16 characters>_<secret>- Public part:
ak_test_orak_live_followed by sixteen characters, lowercase Latin letters and digits. It is not a secret: it names the key in the console and in conversations with support. - Secret: the 43 characters after the second underscore. Only you know it. We store only a hash of the secret, so a lost key cannot be recovered.
Always send the whole key.
How to get a key
An administrator issues keys in the Plutera console: the merchant's card, the "API keys" tab. When issuing a key, they choose the environment and, if needed, an expiry date.
- The whole key is shown once, right after it is issued. After that nobody can see it, including the administrator.
- A merchant can have up to 10 keys at a time, both environments counted. Disabled and expired keys take a slot, revoked keys do not.
- A key can be issued in advance, before the merchant is active. It starts accepting requests once the merchant is activated and the key's environment is opened.
How to send the key
In the Authorization header with the word Bearer:
GET /api/v1/me HTTP/1.1
Host: api.plutera.io
Authorization: Bearer <key>For clients that only support the Basic scheme: send the key as the user name with an empty password. In curl that is -u "$PLUTERA_API_KEY:". A pair with a non-empty password is not treated as a key.
A session of the operator console does not work for the API: a request that carries its cookie is rejected.
Key states
| State | Meaning | Reversible |
|---|---|---|
| Active | Requests are accepted | |
| Disabled | An administrator has temporarily disabled the key | Yes, the key can be enabled again |
| Expired | The expiry date set at issue has passed | No, a new key is needed |
| Revoked | The key was revoked or replaced by regeneration | No, revocation is final |
Replacing a key without downtime
Regeneration revokes the old key and issues a new one in a single action: the old key stops being accepted in the same second. To replace a key without downtime:
- Ask for a second key.
- Move all your servers to it.
- Ask for the first key to be revoked.
When a key is not accepted
Until the secret matches, the response is always the same: 401 without a reason. No key, a malformed key, a key that does not exist, a wrong secret: the response deliberately does not tell these apart, otherwise it would tell an outsider which keys exist.
Once the secret matches, the response names the reason in details.rule. If there are several reasons, one is named, in this order: revocation, expiry, disabling, then the merchant's state, then a closed environment.
All authentication errors with examples: error catalogue.