API keys
All API access requires authentication using a key. Keys can only be created in the control panel by a super administrator. Because the ability to create an API key is very powerful, simply accessing the keys may require an additional password check. This is similar to GitHub's "sudo mode".
When accessing the API, you will always be acting as a particular user. This will be used to know who is creating content or what permissions to use, though there are some exceptions to this which we'll get into later. Therefore, there are three types of API keys:
- Guest keys. This will only be able to access data that a guest can access. To emphasize, a key must still be created, even for guest API access.
- User keys. These keys are tied to a particular user. All actions (such as creating a thread) will be attributed to this user and their permissions will be taken into account.
- Super user key. These are the most powerful keys, and can access the API as any user and bypass the user's permissions if needed. These keys are primarily designed for complex integrations. For example, you may integrate with a third-party CMS that creates a thread whenever you post a new article. This type of key would allow you to create a thread with a different user depending on the article author or in a forum that users normally can't post in.
Super user keys (or user keys attached to privileged users) are very powerful, so it is important that you protect any created API keys so that they can't be used in unexpected ways, such as by bulk deleting threads or even whole nodes.
To help limit the amount of damage that could be done by a compromised key, every key has a set of
allowed scopes:
This screenshot only shows a few of the available scopes. Each content type or action exposed by the API will be covered by some sort of scope. For example, threads and posts are covered by distinct scopes to limit reading, writing (creating/updating/soft-deleting) and hard deleting. For security, you should only give a key the API scopes that you intend to use.
No API key can take a particular action unless it has the relevant scope. For example, if you have an integration that needs a super user key to post a thread, then you would want to give it thread:write (and likely thread:read as well), but you wouldn't want to give it node:delete or user:delete.
(For those of you keeping score, API scopes are what's using the
entity relation values via closures change as discussed on Tuesday. The
type:action convention is in various APIs, so it made sense for us to use it too but that isn't valid as a phrase name.)
To further aid security, whenever an API key is generated or modified, all super admins will be sent an email.
Now that we have an API key, we can start to access the API...
