API Resources

The API supports three methods for making authenticated API requests:

• OAuth 2
• Legacy admin authentication
• Single sign-on

Legacy admin authentication is currently the default API behaviour: when you make requests using your API keys, you are authenticated as the owner of the forum for which the keys were generated. This gives you full read/write access to any of that forum owner's data. Legacy admin authentication does not permit you to authenticate as an arbitrary user; you are always authenticated as the forum owner.

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 20 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:

GET 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, and admin.

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

Once the user allows your application, they'll be redirected to your redirect_uri with the following additional GET parameters:

code

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

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. Exchange this for an 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.

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.