Using OAuth with Desk.com

Before an API call can be made, a registered Desk.com user must first go through the OAuth Authorization workflow and Allow the client application to access Desk.com on behalf of the User. During the process, the user will be required to login to the Desk.com System and “Allow” access. The user will then be redirected to a callback URL configured for the client application with an authorization code which the application can use to retrieve an “Access Token” for subsequent API request access.

OAuth Flow Diagram

Sequence Diagram from OAuth 1.0 http://tools.ietf.org/html/rfc5849


OAuth Endpoints

Type Endpoint
Authorize /oauth/authorize
Request Token /oauth/request_token
Access Token /oauth/access_token

Single Access Token

If you only need to make requests on behalf of a single user, you might want to take advantage of using a single access token. This gives you the equivalent of a site wide API key, giving you the benefit of not needing to go through the entire OAuth token dance. You can immediately start making authenticated requests, similar to the convenience HTTP auth API's provide.

Your token can be found under your client application's details in Admin — General Settings — API Applications. The combination of your consumer key, consumer secret, access token, and access token secret will give you everything you need to immediately make an API request.

Note: Never share the combination of your OAuth consumer key, secret, access token, and access token secret.


Example Code

Here is a ruby example using the standard ruby OAuth library:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
require "rubygems"
require "oauth"

consumer = OAuth::Consumer.new(
        "API_CONSUMER_KEY",
        "API_CONSUMER_SECRET",
        :site => "https://yoursite.desk.com",
        :scheme => :header
)

access_token = OAuth::AccessToken.from_hash(
        consumer,
        :oauth_token => "ACCESS_TOKEN",
        :oauth_token_secret => "ACCESS_TOKEN_SECRET"
)

response = access_token.get("https://yoursite.desk.com/api/v2/users/current")