I have gotten this to work, after some trial and error.
Here are the basic steps that I follow when: I have a separate app that I have coded, and I want users to be able to use that app to make API calls to a discourse site.
To do that, I need to generate a per-user API token to make calls on behalf of each specific user (at least in a nodejs/javascript environment).
Note that for the javascript side of things, I found the code that @KengoTODA provided here: discourse-api-key-generator/index.ts at main · KengoTODA/discourse-api-key-generator · GitHub to be very helpful.
Here are the steps I’ve followed:
First: Generate a public and private key pair.
This is something your app needs to generate–a public key and a private key. The github gist provides one method to do this.
Second: Have a redirect URL.
This is the URL discourse will redirect to, providing the final API token in the payload. If you have a desktop app (ie, doesn’t have a browser URL), the redirect URL will be based on a custom protocol you set up that opens the app when the redirect URL is entered in the browser.
Note that the redirect url needs to be whitelisted on the site settings of the target discourse site.
The discourse site also likely needs to have the site setting checked for “Allow user api keys”. See the original post on this topic for “Site Settings”.
Third: Send the API request call to the discourse request url.
So your app will send a call to a url that follows this form:
https://[your target discourse site .com]/user-api-key-new"
and adding as parameters:
- your app name
- you “client_id” (I was able to use hostname(), from
const {hostname} = require('os')for a desktop app, just like in the github gist referenced above) - scopes (this is the scopes that you want the user to be able to do through the api, like “write”, “read”, etc)
- your public key (from step 1 above)
- your redirect url (from step 2 above)
- nonce (this is a value you can choose–like just using ‘1’ seems to work)
Fourth: User authorizes your app on the discourse site page that is opened by the request url
When you send the request url successfully, it opens a page on the discourse site telling the user your app wants to access the site.
On that page, there is a button for the user to allow this. When the user clicks this button, the discourse site redirects to the redirect url you provided, and attaches as a param a ?payload=[the API KEY]. The API KEY here is the key you need to decode in your app.
Fifth: Your app picks up the redirect url value (with payload value), and you decode the API KEY
You’re almost there. Your app needs to parse the redirect url that discourse went to, and get the API Key contained in the payload.
Once you have that API Key, you need to do two things:
- Get the actual key, not the URL encoded version: if you are getting a param from a url, it is often url encoded (adding % here and there, etc.). You need to clean it up. In javascript, I have found
decodeURIComponentto work for this. - Once you have the cleaned up API KEY returned from discourse, you need to decode it. To do this, you can use javascript decoding with private keys. Basically, you use your private key (generated in the first step above), and to decode the cleaned up API KEY. There is some example javascript in the github gist I referenced above: discourse-api-key-generator/index.ts at main · KengoTODA/discourse-api-key-generator · GitHub
After you run your decoding code, you have the token itself, which you can now use to make authenticated API calls on behalf of the user.
Sixth: Use the token (ie, the final, cleaned up, decoded API Key) to make api calls on behalf of the user
With that token, it appears you don’t need to enter the user name in the api call. I find the following header to be sufficient when you include it in your GET, POST, PUT, etc call:
headers: {
"User-Api-Key": [the token]
}
And with that, you hopefully have a working per-user authentication method to interact with discourse.