API Resources

The API supports the following methods for making authenticated API requests:

• OAuth 2
• Single sign-on

With OAuth, your API requests are considered anyonymous (only public data is returned) until you obtain an access token which permits you to make requests on behalf of a user. To obtain an access token, you redirect users to a special Disqus login page which asks users to grant your application access. OAuth needs to be enabled for your API key.

Access to Single Sign-On (SSO) is available with a Business tier subscription. If you’d like to inquire about a Business subscription, please contact us here . It enables you to make API requests on behalf of an SSO user, given the correct SSO authenticate string.

More instructions below.

Server-Side OAuth

We currently support Draft 30 of the OAuth 2 specification

If you have enabled OAuth2 for your application, which can be done via the edit application page, your requests will always be treated as anonymous unless you are passing a valid access_token.

Authorize The User

Authentication of the user on the server-side will require you to first redirect the user to the Disqus authorize endpoint:

Location: https://disqus.com/api/oauth/2.0/authorize/?
    client_id=PUBLIC_KEY&
    scope=read,write&
    response_type=code&
    redirect_uri=http://www.example.com/oauth_redirect

The available permissions for the scope value are read, write, email, and admin. For more on data availability per scope, see Data Availability.

Note: The domain of redirect_uri must be listed in your application's trusted domains.

Request Access Token

The user will then be given a choice to accept or deny your request. If they choose to allow your application, they will be redirected back to your site with a temporary access code as the code parameter.

The following values are made available as part of the query string when the user is redirected back to your redirect_uri:

code

A temporary token which you will exchange for a finalized access token.

Take the code and exchange it for the user's access_token:

POST https://disqus.com/api/oauth/2.0/access_token/

grant_type=authorization_code&
client_id=PUBLIC_KEY&
client_secret=SECRET_KEY&
redirect_uri=http://www.example.com/oauth_redirect&
code=CODE

See the documentation on the token response for more information.

Authenticating as the Account Owner

Many applications simply want to perform actions on behalf of the account owner. You can do this using the standard OAuth flow, except that you won't need to request an access token. Instead, visit your account details page, and grab the Access Token. This is a special access token which does not expire, and will authenticate you as the application owner.

Making Requests with Tokens

Once you have the access token, you can make requests on the user's behalf. To do this, you simply need to pass the access_token parameter as part of your request:

GET /api/3.0/users/details.json?
    access_token=ACCESS_TOKEN&
    api_key=PUBLIC_KEY&
    api_secret=SECRET_KEY

Note: You should only pass your secret_key if you are using the server-side flow.

Refreshing OAuth Tokens

You will need to obtain a new access_token after expires_in. To do this, you will need to hit the authorize endpoint once again, but with a different set of parameters:

POST https://disqus.com/api/oauth/2.0/access_token/?
    grant_type=refresh_token&
    client_id=PUBLIC_KEY&
    client_secret=SECRET_KEY&
    refresh_token=REFRESH_TOKEN

We recommend you take into account network lag when dealing with the token expiration, and request it before it expires. Also keep in mind, that each user will only have one active token at a time (on your application), so once you refresh the token, the previous token will no longer be valid.

Single Sign-On Authentication

Authenticating users server-side can also be done through our partner Single Sign-On support. To use this, you will need to pass the remote_auth variable with your API request.

Creating a new Application

First, you must authorize a user like before, except with a response_type of api_key:

Location: https://disqus.com/api/oauth/2.0/authorize/?
    scope=read,write&
    response_type=api_key&
    redirect_uri=http://www.example.com/oauth_redirect

After you have a code back, you're ready to exchange that for a new api_key. To do this, you will need to make a request to the api_key endpoint with some optional application descriptors:

POST https://disqus.com/api/oauth/2.0/api_key/?
    grant_type=api_key&
    redirect_uri=http://www.example.com/oauth_redirect&
    code=CODE&
    application[label]=My New Application&
    application[description]=The Application to do the things with&
    application[website]=http://www.example.com/&
    application[organization]=ORGANIZATION&
    application[terms_url]=http://www.example.com/terms&
    application[callback_url]=http://www.example.com/callback

An example response should resemble the following:

{
  "access_token": "c2d06abacfbb40179e47f62f06546ea9",
  "refresh_token": "9182211bf2f746a4b5c5b1e3766443d6",
  "expires_in": 2592000,
  "username": "batman"
  "user_id": "947103743",
  "api_key": "9BGzwXpWUUcJIqbw1jm6NmgylehvSvIWfCqCM63mpkjrAudzhhq7uYGk8ttUxScN",
  "api_secret": "hzUC9yEGgLm9LfbaUdbtzcDhrcFuRPKfyXQC9DwzUWBYFWgD05lASvTB9xgs6Ti3"
}