User API keys specification

(Sam Saffron) #1

Discourse contains a system for generating API keys per user if a very specific protocol is followed:

This feature facilitates “application” access to Discourse instances without needing to involve moderators.

High level description

At a high level:

  1. Client (desktop app, browser plugin, mobile app) generates a private/public key pair and return url

  2. Client redirects to a route on discourse giving discourse its public key

  3. Discourse gets approval from user to use app

  4. Discourse generates a user api key

  5. Discourse redirects back to return url with an encrypted payload using public api key containing the user api key


Use cases:

  1. Desktop applications that poll Discourse sites on behalf of end users to get notification counts across multiple sites.

  2. Mobile applications that poll Discourse sites on behalf of end users and handles push notifications

  3. Web applications that provide a dashboard for end users about various Discourse sites.

  4. Custom integrations with 3rd party apps that consume Discourse as part of a general company app. Eg: integrate Discourse community notifications into hopscotch app.

The design:

Site Settings

  • allow_user_api_keys: default on (allow users to generate api keys)

  • allow_user_api_key_scopes: allowed access scopes for user api keys. Defined here

  • min_trust_level_for_api_keys: 0 (require this trust level for api key access)

  • allowed_user_api_push_urls: list of sites that can be targets for push notifications

  • allowed_user_api_auth_redirects: allowed redirect destinations after user api key generation

Global Settings

  • max_user_api_reqs_per_minute: 20
  • max_user_api_reqs_per_day: 2880

UX changes

User page changes

If any user api keys were granted we will display a new apps tab in the user page.

The apps tab will list:

  • The name of the application eg: (“Discourse Notifier on Sam’s iPhone”)
  • Last use date
  • Level of access (read or read/write)
  • A revoke button so you can easily revoke any keys

API Key authorization UI

Every key will have to be explicitly authorized by end users in a page that clearly explains what is going on, for example:

The application, Discourse Notifier, would like read access to Meta Discourse.
Push notification will be published to

[Grant Access] [Cancel]

API key generation flow

API only requires a single GET request on the users end.




redirect_url: url to redirect back to with the generated token
push_url: url to push notifications to (required and valid only if push access level is requested)
client_id: a unique identifier for the client
access_level: comma delimited list with either: read, write, push

After /api_key/generate is called with correct params 2 things may happen

  1. If user is not logged on, we will redirect to login (after login we will resume authorization)
  2. Once a user is logged on they will be presented with the authorization UI

After authorization is allowed system will redirect back to the redirect_url, this will only include one param which is the api_key that was generated. client_id is not echoed back for extra security.

This is a draft and we are still fleshing out all details.

Consuming the API

Consuming the client API will be somewhat different that the current admin API.

Client can specify 2 headers:

User-Api-Key (required): the key that was generated


User-Api-Client-Id (optional): supply this to update the ‘client id’ stored for this api_key in the database.

Once those headers are specified client can perform requests against the API just as they would normally.

REST API and security
Discourse Login & Registeration
Beta testing the iOS mobile app
Custom Push Notifications: allowed user api push urls
Is there any Discourse Notification API?
Generating User Api Keys with REST API
Generating User Api Keys with REST API
Automatic backups for all the "Download my posts" across discourses
Discourse index
Discourse sso login using Rest API
Automatic login from Windows Application
Generating User Api Keys with REST API
Automatic Login from iOS/Android app
(Eli the Bearded) #2

There are places I’ve strongly considered writing a delayed post tool, so I can compose a bunch of “word of the day” type things to keep going while I’m on vacation. Doing it without proper API access and pretending to be a browser seems somewhat more complicated than on other forum software.

(Just as an example of another use case.)

(Sam Saffron) #3

That is a good example, but keep in mind, our default will be only to enable read tokens, not write ones. Site admins will have to opt to allow write tokens.

Completely agree that the _t cookie hacks are a huge problem.

(Jesse Perry) #4

Does max_user_api_calls_per_key_day setting apply to admin-created keys at /admin/api?

(Sam Saffron) #5

Nope only to user api keys, we can look at adding extra limits for standard Api keys, it is a good safeguard