Some of the Elance Developer API methods, such as the Manage and Workroom methods, are specific to a user's Elance account, and require the user to log in. These API methods are secured using the OAuth authentication protocol, which enables an Elance user to grant an application limited access to their account without sharing their username and password information.

Accessing these methods requires prior approval from Elance. Upon approval, application developers are granted a Consumer Secret that is used for signing all OAuth requests.

The Elance Developer API implements OAuth 1.0 as specified in RFC 5849. All Elance OAuth method requests must use HTTPS. (Unless otherwise specified, the Manage and Workroom methods themselves may be accessed over HTTP or HTTPS.) All Elance OAuth requests must be signed using the HMAC-SHA1 algorithm.

OAuth authentication proceeds according to the following steps:

  1. The client application sends its Consumer Key to Elance using the /oauth/getRequestToken method. The transmission includes a digital signature that is signed using the application's Consumer Secret. Elance responds by sending the client application a Request Token.
  2. The client application creates a redirect URL to /oauth/authorizeToken. The URL contains the Request Token that sends the user to Elance, where the user enters his or her username and password. The client application includes a callback URL that Elance will call after the user has been authenticated.
  3. Elance calls the callback script with the Request Token and a Verification Code. The client application, in the callback script, calls /oauth/getAccessToken to exchange the Request Token for an Access Token.

The Access Token is used to access all authenticated API calls. Once granted, an Access Token is valid for up to six (6) hours. After that, Elance will require the user to authenticate again before further calls can be made against authenticated API methods.

Elance strongly suggests that developers use OAuth using one of the many publicly available OAuth libraries. An extensive list of the libraries available for various platforms can be found on OAuth.net. The information below is provided mainly for the benefit of debugging issues with OAuth authentication.

tableofcontents_number_textElance OAuth Methods

To authenticate a user using OAuth, a client application must use the following three calls in the following order. Two are called as API methods; one (/oauth/authorizeToken) is issued as a redirect to the user. A fourth method, discussed below, may be used to terminate an OAuth session immediately.

tableofcontents_number_text/oauth/getRequestToken

Endpoint: https://api.elance.com/oauth/getRequestToken

This method grants an unauthorized Request Token and a Token Secret to the application. It is called using the HTTP POST method. The following parameters are included as comma-separated name/values pairs in the HTTP Authorization header.

tableofcontents_number_textRequired POST Parameters
Parameter Description
oauth_consumer_key The consumer key used to access all Elance Developer APIs.
oauth_nonce A random value, used in all OAuth authentication requests and all subsequent authenticated API calls to prevent replay attacks.
oauth_token The Request Token. This parameter is left blank.
oauth_timestamp The current time, expressed as seconds since January 1st, 1970. A timestamp value is required in every OAuth authentication call, and in all subsequent authenticated API calls.
oauth_signature_method The cryptographic method used for generating the signature. MUST be HMAC-SHA1.
oauth_signature The HMAC-SHA1 signature encryption of the Consumer Secret and (empty) Token Secret, as described in RFC 5849 section 3.4.2.
tableofcontents_number_textOptional POST Parameters
Parameter Description
oauth_callback An optional URI to the page to which Elance will redirect the user after the user's identity and permissions have been verified. This URI may use any URI scheme. After the user has authenticated, Elance calls this URL, passing the two query string parameters described below. If omitted, Elance displays an HTML page containing the Verification Code; your user must enter this Verification Code manually into your application in order for the application to request an Access Token.

If the user denies your application access to his or her account, this callback is not used.

oauth_version The version of the OAuth protocol being used by this request. The default (and currently only valid value) is 1.0.
tableofcontents_number_textResponse Data Description

The response data is returned in HTTP name/value format as the HTTP body of the server response.

Response Variable Description
oauth_token The Request Token.
oauth_token_secret The Token Secret. The call to /oauth/getAccessToken must be signed using both the Consumer Secret and the Token Secret, as described in RFC 5849 section 3.4.
oauth_callback_confirmed A required response variable in OAuth 1.0 meant to distinguish it from prior versions of the protocol. It is always set to true.
tableofcontents_number_textExample

The unencrypted HTTP headers for an /oauth/getRequestToken request will resemble the following example. Note that all of the OAuth name/value pairs are included in the HTTP Authorization header. An OAuth request may, alternatively, place these values in the POST body of the request. If OAuth name/value pairs are included in both the Authorization header and the POST body, Elance uses the values supplied in the Authorization header.

POST /oauth/getRequestToken HTTP/1.1
User-Agent: anyMeta/OAuth 1.0 - ($LastChangedRevision: 134 $)
Host: api.elance.com:443
Accept: */*
Authorization: OAuth realm="",oauth_signature_method="HMAC-SHA1",oauth_signature="V0E940D1UO8rPpEzyzUVfC2pyCI%3D",oauth_nonce="4c894e290453d",oauth_timestamp="1284066857",oauth_token="",oauth_consumer_key="8dec476c57fee5b7dc08cc0f1d5a0fcdab409b3c",oauth_version="1.0"
Content-Type: application/x-www-form-urlencoded
Content-Length: 0

tableofcontents_number_text/oauth/authorizeToken

Redirect URL: https://api.elance.com/oauth/authorizeToken

The Elance Developer API issues an unauthorized Request Token upon a successful /oauth/getRequestToken call. The client application next directs the user to the URL /oauth/authorizeToken to request that Elance authenticate the user. After Elance has verified the user's credentials (username and password), it calls a URL specified by the client application (the callback URL).

/oauth/authorizeToken is sent as a redirect to the client application, and therefore is invoked using the HTTP GET method. The following parameters are appended to the URL query string.

tableofcontents_number_textRequired Query String Parameters
Parameter Description
oauth_token The Request Token returned by /oauth/getRequestToken.
tableofcontents_number_textResponse Data Description

If oauth_callback is specified, this data is passed in the query string of the callback URL.

Response Variable Description
oauth_token The Request Token. Used by the client application to associate the callback with a prior call to /oauth/getRequestToken.
oauth_verifier The Verification Code. This value must be included in a subsequent request to /oauth/getAccessToken in order to exchaneg the Request Token for an Access Token.

tableofcontents_number_text/oauth/getAccessToken

Endpoint: https://api.elance.com/oauth/getAccessToken

Having received the Request Token in the callback, the client application calls /oauth/getAccessToken with both the Consumer Secret and Token Secret, and exchanges the Request Token for an authorized Access Token. The Request Token used up until this point is discarded. The client application can now access the authenticated methods in the Elance Developer API using the authorized Access Token.

tableofcontents_number_textRequired POST Parameters
Parameter Description
oauth_consumer_key The consumer key used to access all Elance Developer APIs.
oauth_token The Request Token returned in the callback generated by oauth/authorizeToken.
oauth_nonce A random value, used in all OAuth authentication requests and all subsequent authenticated API calls to prevent replay attacks.
oauth_timestamp The current time, expressed as seconds since January 1st, 1970. A timestamp value is required in every OAuth authentication call, and in all subsequent authenticated API calls.
oauth_verifier The Verification Code returned by the redirect to /oauth/authorizeToken.
oauth_signature_method The cryptographic method used for generating the signature. MUST be HMAC-SHA1.
oauth_signature The HMAC-SHA1 signature encryption of the Consumer Secret and Token Secret, as described in RFC 5849 section 3.4.2.
tableofcontents_number_textOptional POST Parameters
Parameter Description
oauth_version The version of the OAuth protocol being used by this request. The default (and currently only valid value) is 1.0.
tableofcontents_number_textResponse Data Description

The response data is returned in HTTP name/value format as the HTTP body of the server response.

Response Variable Description
oauth_token The authenticated Access Token.
oauth_token_secret The Access Token Secret. This value and the Consumer Secret must be used to sign all subsequent authenticated API calls.

tableofcontents_number_text/oauth/revokeToken

Endpoint: https://api.elance.com/oauth/revokeToken

Calling this endpoint will cause the Access Token included with the request to expire immediately.

Parameter Description
oauth_consumer_key The consumer key used to access all Elance Developer APIs.
oauth_token The Access Token.
oauth_nonce A random value, used in all OAuth authentication requests and all subsequent authenticated API calls to prevent replay attacks.
oauth_timestamp The current time, expressed as seconds since January 1st, 1970. A timestamp value is required in every OAuth authentication call, and in all subsequent authenticated API calls.
oauth_signature_method The cryptographic method used for generating the signature. MUST be HMAC-SHA1.
oauth_signature The HMAC-SHA1 signature encryption of the Consumer Secret and Token Secret, as described in RFC 5849 section 3.4.2.
tableofcontents_number_textOptional POST Parameters
Parameter Description
oauth_version The version of the OAuth protocol being used by this request. The default (and currently only valid value) is 1.0.

tableofcontents_number_textError Codes

OAuth-related error codes are of the error type authentication, and are documented in Common API Error Codes.

tableofcontents_number_textTroubleshooting OAuth

I've authenticated successfully. Now I'm getting the error E_API_AUTH_SIGNATURE_MISMATCH whenever I try and access a method that requires authentication.

Signature mismatch issues are one of the most bedeviling aspects of OAuth. They occur when your client application and the Elance API calculate a different encrypted signature for a specific request. Following are some of the most common causes.

Bad Request Token

If the Request Token the client application submits to the server does not exactly match the Request Token returned by /oauth/authorizeToken, the server will return this error. Check that the Request Token value is correct, and re-submit the request.

Invalid System Time

If the computer from which you are calling Elance OAuth-enabled API methods has a date or time that differs from network time by more than several minutes, Elance will reject the signed request. Use a Network Time Protocol (NTP) server utility to synchronize the client application's system clock with network time, and try the request again.

Mismatched Parameter(s)

All of the query string or POST parameters included in your request are used to help calculate what is known in OAuth as the Signature Base String (SBS). The SBS is a repeatable concatenation of elements from the API request - the HTTP request method, the URL, and the list of GET or POST parameters - that is used as the base text for creating the method signature using the HMAC-SHA1 encryption algorithm.

If the name of any of the submitted parameters to an Elance API authenticated method call differs from the actual name, the Elance API will ignore it, causing it to generate a different signature than the one generated by the client. Double check the spelling of all parameter names before attempting the request again.

Error in Calculating The Signature Base String

If you've written your own OAuth client routines, there's a chance you've made an error in calculating the SBS. To double-check your work, enter all of the values for your OAuth request into the OAuth Signature Test Tool on GoogleCode, which will compute the normalized parameters, the Signature Base String, the signature, and the Authorization header. If these values don't match the values calculated by your application, double-check your implementation against the OAuth 1.0 specification.