# User API keys specification **URL:** https://meta.discourse.org/t/user-api-keys-specification/48536 **Category:** Integrations **Tags:** rest-api, reference **Created:** [August 12, 2016, 2:11am UTC](https://meta.discourse.org/t/user-api-keys-specification/48536 "2016-08-12T02:11:53Z") **Posts on this page:** 1 **Showing post:** 1
### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse) #### Post date: [August 12, 2016, 2:11am UTC](https://meta.discourse.org/t/user-api-keys-specification/48536/1 "2016-08-12T02:11:53Z")
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 ### Details 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\_key\_scopes** : allowed access scopes for user api keys. Scopes are defined [here](https://github.com/discourse/discourse/blob/main/app/models/user_api_key_scope.rb). The available built-in scopes are: `read`, `write`, `message_bus`, `push`, `one_time_password`, `notifications`, `session_info`, `bookmarks_calendar`, `user_status` (plugins may register additional scopes). - **user\_api\_key\_allowed\_groups** : controls which groups are allowed to generate user API keys (defaults to admins, moderators, and trust\_level\_0) - **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** : 50 - **max\_user\_api\_reqs\_per\_day** : 4000 ### UX elements If any user api keys have been granted, Discourse displays an **apps** tab in the user page. The **apps** tab will list: - The name of the application eg: (“Discourse Notifier”) - Last use date - Approved date - List of access scopes granted - A **revoke access** 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: > “Discourse Notifier” is requesting the following access to your account: > > - Read and clear notifications > - Read user session info > - Create a one-time login token > > [Authorize] ### API key generation flow API only requires a single GET request on the user’s end. ```plaintext https://sitename.com/user-api-key/new ``` > ❗ As of Discourse 2.1 these user api keys now auto-expire if left unused for long periods of time. The site setting: `revoke user api keys unused days` is set to 180 out of the box Params: - **auth\_redirect** : url to redirect back to with the generated token - **application\_name** : the name of the application making the request (will be displayed in the user account’s Apps tab) - **client\_id** : a unique identifier for the client - **nonce** : a unique nonce generated by the client. This will be echoed back in the encrypted payload so the client can verify the response authenticity - **scopes** : comma-separated list of access scopes allowed for the key, see `allow user api key scopes` for the full list of available scopes - **push\_url** : url to push notifications to (required and valid only if `push` or `notifications` are included in the scopes) - **public\_key** : the public part of the keypair generated by the client - **padding** (optional): the RSA padding mode to use for encrypting the payload. Accepted values are `pkcs1` (default) or `oaep`. OAEP is recommended for new applications After `/user-api-key/new` 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 URL defined in `auth_redirect` and include an encrypted `payload` parameter containing a JSON object with the generated user API key (`key`), the `nonce`, push status (`push`), and API version (`api`). If the `one_time_password` scope was requested, a separate encrypted `oneTimePassword` query parameter will also be included. `client_id` is not echoed back for extra security. ### Checking API version The use key API in Discourse is versioned. Clients can check a Discourse site’s API version by making a HEAD request to `https://sitename.com/user-api-key/new`. The response will contain a header named Auth-Api-Version containing the version number of the site’s API. ### 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 and `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. ### Generating a one-time-login password As of version 4, the API includes a special scope: the `one_time_password` scope, which allows clients to use the user API key to generate a one-time-password. If the client includes this scope when generating the API key following the steps above, an encrypted `oneTimePassword` will be included as a separate query parameter in the redirect back to the client. Alternately, the client can make a GET request to `/user-api-key/otp` with the following parameters: - auth\_redirect - application\_name - public\_key - padding (optional) and with the `User-Api-Key` header. This request will redirect to a screen in Discourse that will ask the user to allow the application access to the site. If the user approves, the site will redirect back to the URL defined in `auth_redirect` and include an encrypted `oneTimePassword` parameter with a one-time password which the client can use to login to the site by requesting `https://sitename.com/session/otp/ONE-TIME-PASSWORD`. (The one-time-password is only valid for 10 minutes.) ### Revoking API keys To revoke an API key, make a POST request with the `User-Api-Key` header and no params to `/user-api-key/revoke`. * * * _Last Reviewed by @SaraDev on 2022-07-13T00:00:00Z_ --- _[View the full topic](https://meta.discourse.org/t/user-api-keys-specification/48536)._