I’m hoping to clarify when and for what purposes the two Discourse API Authentication systems operate.
(from here). This is my best understanding:
The Admin API, sometimes also referred to as the JSON API, can be used when you want to make API calls to interact with a Discourse forum and either:
- those calls do not require any authentication, or
- those calls do require authentication, but you have direct control over the Discourse forum too, so you can manually generate API keys that your forum and/or the separate app can use to make the API calls.
The User API, on the other hand, is meant for when you want to interact with a Discourse forum (or forums), the interactions require authentication, and you do not control the forum (or forums) you want to interact with.
Another way of saying it: the Admin API is for when you control the forum you’re interacting with, and the User API is for when you don’t control the forum.
Is this correct?
For example, @david’s description here says that the Admin API is not meant to be used with javascript clients. But I believe it’s fine to use the Admin API with javascript clients so long as the owner of the app the javascript clients use also controls the forum. (ie, the owner of the separate app is the same as the owner of the forum.) Right?
I’d think that’s how it works. If you want to make calls to the Admin API regarding a Discourse site from a separate app, then I believe you can make those calls server side (from a backend). If you don’t make them from a backend–and make them from the client side, you may run into CORS restrictions. In that case, you can whitelist the domain of the separate app at admin/site_settings/security/ → “cors origins”.
Below I’ve also included more details on how these APIs work. One other question I still have: when you are setting an API Key for the Admin API, when is using “All Users” as the user level appropriate?
Further Detail:
The Admin API
The Basics
This is the API described at docs.discourse.org. Sometimes referred to as the JSON API.
By interacting with the endpoints of this API, you can do just about anything you could do directly on a Discourse site, using the method described here.
Certain endpoints require authentication. For example, if you want to use the API to retrieve details of a particular group (endpoint: [your-forum]/groups/[group-name].json), but that group is only visible to its members, then you’d need to make the call to the endpoint “on behalf of” one of the members.
To get make the API call using proper authentication, you’d need to generate an API key at [your-forum]/admin/api → New API Key, selecting for that key the User Level “Single User”, and choosing a user authorized to view the resource (such as information about a group).
When you then make the API call, you include headers: the key as Api-Key and the user’s username as Api-Username.
There’s also the option, when setting the API Key, to choose “All Users”. Per my question above, I’m not sure when this is appropriate versus, say, choosing a single user and having that user be the Admin.
When To Use
You can use the Admin API from “within” your Discourse app. So you can interact with the Admin API: (i) from the Edit CSS/HTML dashboard for each theme under [your-forum]/admin/customize, (ii) from a theme that you integrate into your discourse site, and (iii) from a plugin that you integrate into your discourse site.
You can also use the Admin API from a separate app, if you control the Discourse forum so that you can, through the forum, manually generate the API key(s) that the separate app will use.
Per my question above, this is the understanding I’m hoping to confirm.
The User API
The details of this API are described here: User API keys specification
I believe the User API exists because the Admin API is not meant to be used as a general API accessible to any site or app separate from your forum.
To be clear on that: there are two different scenarios where a separate app might interact with your Discourse forum:
Scenario 1: No Direct Connection: A developer that is not connected to the Discourse forum creates and app that interacts with the forum. For example, a developer who is not the admin of the forum or otherwise connected to the admin of the forum wants to make an app that polls various Discourse sites to get some facts about them or info back from them.
In this scenario, the Discourse forum admin is not going to manually generate an API Key to give out to the unconnected developer. So the Admin API is not appropriate.
So, just like many sites like Youtube have an API that third party developers can use to interact with Youtube on the apps they make, the Discourse User API is a way for third party apps to interact with your forum by having the clients (desktops, mobile phones) using the apps generate an API key that gives them limited access to the forum.
Scenario 2: A Directly Connected App The admin of a forum (or a developer connected to the admin) is connected to a separate app that the admin wants to interact with the forum.
For example, maybe an admin wants there to be a separate app with non-Discourse features, and he/she wants there to be overlap between the users of the separate app and the forum. In this case, the Admin can actually directly (manually through the forum admin dashboard) generate the API keys and provide those to the separate app to use, so that the separate app can utilize the Admin API.