I’m hoping to clarify when and for what purposes the two Discourse API Authentication systems operate. [image]API CORS Headers Incorrect We have two different API authentication systems, which can be confusing. (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.

[image] JQ331: 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? If you ship an API key in your application it is trivial for a hacker to fish that key out of the application binary or wire protocol. The user API is immune to this problem, user approves the application and then gets an dedicated API key generated.

[image] sam: The user API is immune to this problem, user approves the application and then gets an dedicated API key generated. What is the key use case for the Admin API? In my case, I am using it to: Add things to my forum, by making API calls that send data I show on my forum. An alternative method of doing this would be to, through a plugin, add ember/rails code to create different types of data and display it. I’m using the API (at least for now) because from a programming perspective it’s a lot easier to understand the API and use javascript to interact with it then it is to master the discourse code base and become fluent in ember and rails. Allow a separate app I have to interact with my forum. In both cases, the user API would not work, because the data that needs to be retrieved and shown is often not specific to the user. I understand your point that, basically, you don’t want an API Key exposed on the front end. To address this while still using the Admin API, I house the key on a backend, that I make a call to from my forum. So the forum exposes the backend endpoint URL (not a concern), but not the API Key housed there.

[image] JQ331: Allow a separate app I have to interact with my forum. [image] JQ331: In both cases, the user API would not work, User api was designed for this, see the source code of Discourse Hub for a reference implementation.

What is the admin api designed for?

Admin API is for server-to-server interactions, e.g. calls made from the backend of a website.

The purpose of the 2 Discourse API systems

Product Support

sam (Sam Saffron) June 24, 2020, 12:25am 4

User api was designed for this, see the source code of Discourse Hub for a reference implementation.

Topic		Replies	Views
Allow API use by regular users, not just admins Development rest-api	6	1646	February 14, 2023
User API keys specification Integrations rest-api , reference	69	38585	September 22, 2025
Create apikey for user programmatically as admin Development rest-api	8	2237	February 26, 2024
Can non-admin user issue their own API key? Development rest-api	13	3058	September 2, 2021
Online User API? Development	2	1988	March 20, 2016

The purpose of the 2 Discourse API systems

Related topics