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:
Client (desktop app, browser plugin, mobile app) generates a private/public key pair and return url
Client redirects to a route on discourse giving discourse its public key
Discourse gets approval from user to use app
Discourse generates a user api key
Discourse redirects back to return url with an encrypted payload using public api key containing the user api key
Desktop applications that poll Discourse sites on behalf of end users to get notification counts across multiple sites.
Mobile applications that poll Discourse sites on behalf of end users and handles push notifications
Web applications that provide a dashboard for end users about various Discourse sites.
Custom integrations with 3rd party apps that consume Discourse as part of a general company app. Eg: integrate Discourse community notifications into hopscotch app.
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
- max_user_api_reqs_per_minute: 20
- max_user_api_reqs_per_day: 2880
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:
/api_key/generate is called with correct params 2 things may happen
- If user is not logged on, we will redirect to login (after login we will resume authorization)
- 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.