Overview
As an alternative to the Auth-ID,
requests to the mailbox API (https://api.mailbox.org/v1/) can be
authenticated with a static API key. The API key is independent
of a session: there is no auth call, and the key is sent with
every request.
Every request authenticated with an API key runs with the permissions of the mailbox account that owns the key.
Create an API key
API keys are created and managed in the mailbox console, in the user profile under API access:
Each key has a name and a validity of 30 days, 90 days, 1 year or unlimited.
The complete key is shown only once, directly after it has been created. Store it securely immediately. The public key ID shown in the key list cannot be used for authentication.
Deleting a key in the console revokes it immediately.
Send the API key with the HTTP header
The API client sends the key with the HTTP header X-Api-Key:
X-Api-Key: <your API key>
Example:
curl -s https://api.mailbox.org/v1/ \
-H 'Content-Type: application/json' \
-H "X-Api-Key: $(cat ./customer.apikey)" \
-d '{"jsonrpc":"2.0","method":"hello.innerworld","params":{},"id":"1"}'Do not send the HPLS-AUTH header in the same request: if it is present, the Auth-ID is used and the API key is ignored.
The mailbox CLI sends this header automatically.
Errors
If the API key is unknown, expired or deleted, or if its owner is not allowed to log in, the following error will be returned:
{
"jsonrpc":"2.0",
"error":{
"code":493,
"message":"API key authentication failed"
},
"id":"1"
}Check the key in the mailbox console and, if necessary, create a new one.
Error 494 (API key authentication temporarily unavailable, please try again later) is a temporary problem on our side. Repeat the request later.
Security note
Store the API key securely and never share it with unauthorized persons. Treat it like a password. If you suspect misuse, revoke the key immediately and generate a new one.
Do not put the key into URLs, logs, tickets or your shell history.