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.

Single sign-on authentication is only for SSO users (Pro and VIP accounts). 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.

Password Credentials OAuth

Certain applications may not have full access to a standard web-style authorization flow. This is ideal for desktop and mobile applications. Given this, we also support authorization by requesting the client's username and password. This type of flow is restricted to approved applications only, so you must request access first.

Request Access Token

The request and response cycle consists of a single web request, that upon success will yield an access token:

POST https://disqus.com/api/oauth/2.0/access_token/?
       grant_type=password&
       client_secret=SECRET_KEY&
       client_id=PUBLIC_KEY&
       scope=read,write

This relies on HTTP Basic Authorization. In this case, the Authorization header should contain the following value:

Authorization: Basic BASE64(USERNAME:PASSWORD)

See the documentation on the token response for more information.

Authorization Response

The response will contain (at minimum) the following parameters:

access_token

The users access token for future requests.

refresh_token

The refresh token as described in the OAuth spec.

expires_in

The number of seconds from now that this token will expire in.

The following values, which are not part of the OAuth spec, are also sent back:

username

A string representing the authenticated user's username.

user_id

A string representing the internal identifier for the authenticated user.

An example response should resemble the following:

{
  "access_token": "c2d06abacfbb40179e47f62f06546ea9",
  "refresh_token": "9182211bf2f746a4b5c5b1e3766443d6",
  "expires_in": 2592000,
  "username": "batman"
  "user_id": "947103743"
}

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"
}