API keys are generated from the Admin / API page. Go to Admin-Advanced-API Keys:
After clicking the “New API Key” button, you will be taken to a page to configure the key:
Every API key needs a description, a user level, and a scope.
Description
The description can be anything that you choose.
User Level
The User Level drop down allows you to select either “All Users” or “Single User.” If “All Users” is selected, the key can be used on behalf of any user. This is done by setting the user on whose behalf you are making the request for as the Api-Username in the request headers. (See the Authentication example in the API docs for details about how to set the request headers.)
If “Single User” is selected, a user field will appear on the form. Enter the username of the user you are generating the API key for into that field:
Scope
The Scope drop down allows you to select either “Granular”, “Read-only”, or “Global” as the scope.
If “Read-only” is selected as the scope, the API key will only be able to be used to make GET requests. The key will be able to make any GET requests that the user who the key was generated for, or the username that’s entered as the request’s Api-Username has permission to perform.
If “Global” is selected as the scope, the key can be used for any requests that the user who the key was generated for, or the username that’s entered as the request’s Api-Username has permission to perform.
If “Granular” is selected as the scope, a form that allows you to select from the available scopes will be opened. Hover over a scope’s question mark icon to see a description of the scope. Click the scope’s link icon to see a list of paths and request methods that the scope supports. Note that many of the scopes allow you to enter an additional parameter to limit what paths on the site the scope will allow access to:
After configuring the API key and clicking the Save button, the full API key will be shown to you once. Be sure to copy the key as there is no way to view the full key again.
Additional reading
Details about the rate limits that Discourse applies to API keys: Global rate limits and throttling in Discourse.
Discourse API docs: https://docs.discourse.org/.
A helpful guide for figuring out how to structure API requests: How to reverse engineer the Discourse API.
Last edited by @JammyDodger 2024-05-26T06:45:21Z
Check document
Perform check on document:
icon.
