Keys and scopes
What each kind of key reaches, and the scopes a key can hold.
There are two kinds of key, and each reaches only its own calls.
| Key | Starts | Made in | Reaches |
|---|---|---|---|
| An organisation's key | f365_live_ten_ |
Customer portal, Developers > API keys | That organisation's people, signatures, templates, rules, campaigns and recipient lists |
| A reseller's or distributor's key | f365_live_res_ |
Reseller portal, Account > API keys | Its customers and their seats |
An organisation's key reaches none of the customer calls, and a reseller's key none of the organisation calls. A call made with the wrong kind of key is refused with 403 and the code reseller_key_required or scope_missing.
What is stored
The key itself is never stored, only a keyed hash of it, so Footer365 cannot show a key again. Only its prefix, such as f365_live_ten_9f2c81a4bd07, is shown afterwards. A lost key is revoked and replaced. A revoked key is refused everywhere within a minute.
A key can be given an expiry date and a list of addresses it may be used from. A call from any other address is refused with 401 and the code address_not_allowed.
A key can do no more than its maker
When a key is made, it can be given only scopes its maker could use in the portal at that moment. The customer portal flags a key whose maker has since lost access to something the key can do; the key keeps working until it is revoked.
Templates, rules and campaigns in a folder with its own access list are reached only when the folder gives Everyone with View signatures access, and then only to the level that entry gives.
A key made by an administrator limited to part of the organisation carries that limit and reaches no further than its maker. It reads and changes only the people in that part, reads every rule and campaign but changes only those aimed wholly inside it, and is refused with rule_outside_scope or campaign_outside_scope for any other. Its campaigns come back without click counts when they are aimed beyond it. It cannot change a recipient list, which belongs to the whole organisation, and is refused with list_organisation_wide. GET /v1/me names the part in limitedTo.
Scopes
An organisation's key
| Area | Read | Change |
|---|---|---|
| People and their details | directory.read | directory.write |
| Templates and signature HTML | templates.read | templates.write |
| Signature rules | rules.read | rules.write |
| Campaigns | campaigns.read | campaigns.write |
| Recipient lists | None | lists.write |
Change never includes read: a key that needs both is given both. A person's signature HTML needs templates.read. Recipient lists have no read scope, because a list keeps each address only as a one-way code and cannot give it back.
A reseller's or distributor's key
| Scope | What it reads |
|---|---|
customers.read | Its customers, their subscriptions and seats. A distributor's key reaches its resellers' customers too. |