Your first API request
Make this call before your first send. It touches nothing, costs nothing, and answers the two questions that cause most first-day confusion: is my key valid, and what is it allowed to do.
curl https://api.lockally.com/v1/auth/whoami \
-H "Authorization: Bearer $LOCKALLY_API_KEY"
{
"tenant": {
"slug": "acme",
"name": "Acme Ltd",
"plan": "starter"
},
"scopes": ["send:write", "send:read"],
"auth": "api_key",
"key": {
"id": "b1e4c0de-5a2f-4c7e-9d31-0a8f6b2c4d99",
"label": "Production backend"
}
}
What it tells you
scopes is the list your key actually holds. Compare it against the
scope the endpoint you are about to call requires, which is in the
API Reference. Scopes cannot be added to a key
after it is created, so a missing one means a new key, not an edit.
tenant.plan matters because API access is checked on every request,
not only when the key is made. A plan without API access stops every key at
once, and restores them if you move back.
auth is api_key here. It reads session when the call comes from a
signed-in console session instead, and then there is no key object.
key.label is the label you typed when creating it. If you are holding
several keys, this is how you confirm you are using the one you think.
If it fails
401 Unauthorized. The key is missing, malformed, revoked, or presented
as the wrong kind. A key issued as lk_test_ cannot be sent as lk_live_ or
the reverse; authentication fails rather than quietly doing the wrong thing.
Check you copied the whole key, including the prefix.
Connection refused or a certificate error. Check the base URL. It is
https://api.lockally.com, not app. (the console) or mail. (webmail).
403 with the title Business mode required. Your key is fine. You have
called an endpoint that needs hosted mailboxes from an API-only account. See
Business, API and Both.
Next
Send something: Send your first email. Or read what comes back first: Understanding responses.