Discourse API Documentation

Just noticed the deprecation warning:

  • We detected an API request using a deprecated authentication method. Please update it to use header based auth.

Anybody know when it is going to be removed completely? (i.e how long have we got before we need to update?)

Great to see there’s a Discourse api gem btw! Should make things a lot easier :smiley:


We don’t have a specific timeline set for this. At minimum a month or two, could be longer.

Thanks for bringing this up. We are considering some options to keep support for private rss and such in some way.


After having lost half a day chasing the rabbit :slight_smile: I want to share one subtle change that goes on top to moving api_key and api_username into the header of the request.

Parameters names in the request payload (deprecated)

api_username, with an underscore
api_key, with an underscore

Parameters names when used in the Header

Api-Username, with hyphen (or dash)
Api-Key, with a hyphen (or dash)

For me this was almost impossible to see, and I banged my head against the wall countless times fighting 403 [BAD CRF] error before spotting that we moved from underscore to dashes.

You out there don’t laugh at me :stuck_out_tongue:


Never! :rofl: Many of us have had similar “experiences.” :innocent:


Would it be possible to add a private access key similar to how reddit’s private feeds work? That would be the simplest solution I would think.

1 Like

Does the HTTP header based authentication has strictly the same behavior? I remember when the HTTP headers were available I tried them and I got weird behaviors where sometimes it did not work as expected. I know it’s vague, but I had no time to investigate back then. I’m just worried that since we are forced to update all our code, new issues will arise suddenly.

1 Like

Yes. Nothing else should change behavior wise. Just need to move the location of the api credentials.

Maybe you are thinking of the User API keys specification? Which is different than just using the full api.


Thanks for pointing this out, though, it wasn’t enough to entirely prevent my head-banging. Apparently remembering this and enacting it are two different things. :wink:


I’m getting the warning about authentication in the admin dashboard. I do have an API key which is being used every couple minutes, but I don’t know of any process that should be using it. How can I find out what the API request was, or maybe what IP it’s from? I don’t see anything in the logs.

EDIT: It may be SSO with Wordpress- will look more later.

1 Like

After seeing when the API was last used, you could try switching to Users to see if there have been any logged in (last seen) within the same time frame. That may be a quick way to help verify if it was SSO using it.

If you are using an up to date version of the WP Discourse plugin for SSO, it should not be the cause of the warning.


Sorry, I’m not a WP guy. This screenshot is from /wp-admin/plugins.php. There is no button to update, so I think this means it’s using v1.9.7, which matches the latest version at Releases · discourse/wp-discourse · GitHub.

So the question remains how to tell what process or IP is using that API key.

1 Like

You can grep the nginx logs for api-key and get its ip number, which might be a hint.


I have a API deprecation notice but have no clue what’s causing it. We have the WordPress / Discourse plugin installed (and up-to-date) but according to the dev this should not cause the notice. How do i find out whats causing this notice?

1 Like

Do you have any api keys listed under the admin / api section? Are they different than what the Wordpress plugin is using?


Yes, one for “all users” as is suggested (with publishing name set to “system”) and one for an admin account. I’ve tested both in WordPress, and turned them on/off in Discourse but tthe notice remains.

1 Like

Thank you for looking into the number of API keys you have.

There is a 24 hour delay for the notification to go away. So once Discourse detects a deprecated api request it restarts the 24 hour clock.

Now that we know you have two api keys and it sounds like the only one you are aware of is for WordPress you can probably just create a new api key just for WordPress and delete the two original ones. This way we know for sure you only have one key being used and what is using it.


The issue with the WP Discourse plugin’s authentication methods was dealt with a couple of months ago, so as long as you’re on a recent version of the plugin, it shouldn’t be causing the notification that you are seeing. Do you have the WP Discourse Shortcodes plugin installed on your site? If so, I updated it last week to use header based authentication for its API calls. I don’t think that plugin is installed on many sites though.


Now that this API deprecation warning:

has had several months to simmer, I wanted to let everyone know that we will be fully deprecating API credentials in query parameters on April 6th, 2020. It will be available to self-hosters shortly thereafter when the next beta release is out.

During November 2019 we released an update to your admin dashboard that would appear if it detected this deprecated API authentication method. Please check your admin dashboard for this message and make the appropriate changes to any API integrations you may have. If you do not see this message you either have an API integration that triggers less than once every 24 hours or you don’t have any affected API integrations and have nothing to update.

We are making this change in an effort to further increase the security of all Discourse sites by removing the support of API authentication credentials inside of query parameters and requiring that authentication credentials are passed inside of HTTP Headers.

The only API endpoints that will not be affected and will continue to have support for credentials in query parameters will be requests to RSS feeds and the Mail Receiver endpoint.


Running through this change - it doesn’t look like the Api-Key or Api-Username headers have been added to the Access-Control-Allow-Headers setting - discourse/008-rack-cors.rb at master · discourse/discourse · GitHub

Once this deprecation comes in, the API will no longer be accessible programmatically - at least in the way we’re currently using it.

Am I missing something obvious here?

Duplicate here: API CORS Headers Incorrect

Although this was closed by @david I disagree with his explanation. There are scenarios where we want to generate an API key on behalf of a user, without them having to get approval from the user. In our use case, the API key generation should very much remain ‘hidden’ from the user, and hence our only choice is to use the Admin API keys, rather than User API keys.

I understand it’s not as simple as enable CORS by default for the Admin API headers, but this should at least be configurable in the same way that CORS origins are…

1 Like