Learn how to use OAuth with LinkedIn's APIs. Some basic knowledge of OAuth required.

1. ZERO to HERO
The LinkedIn OAuth Dance

2. Using the LinkedIn API is easy...
If you’re lord of the dance.

3. The OAuth Dance

4. OAuth is an open authorization standard for
APIs that does away with logins and passwords
to grant authorization to a third-party.
Some familiarity with OAuth is assumed, going
forward.
http://oauth.net/core/1.0a

5. Will any old OAuth library work with LinkedIn?
LinkedIn uses OAuth 1.0a and requires
HTTP Header-based Authorization.
Some OAuth libraries don’t yet support
OAuth 1.0a, or are built with lenient
OAuth implementations in mind.
LinkedIn’s OAuth is strict.Your library
might not be up to snuff.

6. You might have to get your hands dirty.

7. Quick Glossary That Won’t Be So Quick
Because This Stuff Actually Takes Time to Learn
oauth_callback - This is either a URL or “oob” and denotes where to direct a user on your server following the “authorize”
step.
out of band - A form of OAuth where no URL callback is used and an oauth_verifier challenge is presented instead
requestToken - a token issued to you as a result of asking for it. Re-used in the authorize step
accessToken - a token issued to you at the end of the cycle. Represents a LinkedIn member and authorizes you to access
resources on their behalf
authorize - After getting a request token, you send the user to a signed authorize URL where they grant access to your
application
token secret - a string returned on the requestToken and accessToken steps, used in conjunction with your consumer secret
when signing certain requests.
consumer key - Your API key.
consumer secret - Your API secret. Used in the signing of all requests.
oauth_nonce - A random string, unique in every request.
oauth_timestamp - Epoch time in seconds, synced within 5 minutes of LinkedIn’s clock
oauth_token - Specified in many contexts, either the request token or access token.
oauth_verifier - A returned to you when your oauth_callback is invoked, or hand-entered by a user in the out-of-band flow.

8. All OAuth-based requests are very similar.You’re identifying a
resource that you want to make a request to, you’re building a
string that describes the request and your credentials for making
it, and then you’re signing that string using a set of secrets.
It’s like addressing an envelope where the address and stamp not
only describe the destination but also the contents.
The OAuth 1.0a Request Cycle

9. 1) You ask for a request token and specify your callback
2) You direct the user to our authorization screen
3) You either receive a callback at a URL you specified, or the
member enters a PIN code (out-of-band authentication)
4) You ask for an access token
5) You make API calls!
The OAuth 1.0a Request Cycle

10. Building a requestToken request requires the following:
HTTP Method, Request URI, oauth_callback, oauth_consumer_key,
oauth_nonce, oauth_signature_method, oauth_timestamp, and
oauth_version.
Getting a Request Token

11. First build your string to sign.
We’ll use these values for this example.
HTTP Method POST
Request URI https://api.linkedin.com/uas/oauth/requestToken
oauth_callback http://linkedin.realitytechnicians.com:3000/oauth_consumers/taylor_singletary/callback
oauth_consumer_key dTgSkaRKZjEnS1vAUu6e7-aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV
oauth_nonce 24FZIeB9tNGlnV9p7nnP1yelQbTNFjU7R5qs8u0tk
oauth_signature_method HMAC-SHA1
oauth_timestamp 1260811626
oauth_version 1.0
Getting a Request Token

12. First build your string to sign.
These parameters get sorted alphabetically, each value is URL escaped, and than
concatenated into a single string.
POST&https%3A%2F%2Fapi.linkedin.com%2Fuas%2Foauth
%2FrequestToken&oauth_callback%3Dhttp%253A%252F
%252Flinkedin.realitytechnicians.com
%253A3000%252Foauth_consumers
%252Ftaylor_singletary%252Fcallback
%26oauth_consumer_key%3DdTgSkaRKZjEnS1vAUu6e7-
aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV
%26oauth_nonce
%3D24FZIeB9tNGlnV9p7nnP1yelQbTNFjU7R5qs8u0tk
%26oauth_signature_method%3DHMAC-
SHA1%26oauth_timestamp
%3D1260811626%26oauth_version%3D1.0
Getting a Request Token

13. Create your Authorization HTTP Header & Issue the Request
Now we sign this string using our consumer secret and create an HTTP Authorization header,.
The signature should be placed in the oauth_signature value.
Authorization: OAuth
oauth_nonce="24FZIeB9tNGlnV9p7nnP1yelQbTNFjU7R5qs
8u0tk", oauth_callback="http%3A%2F
%2Flinkedin.realitytechnicians.com
%3A3000%2Foauth_consumers%2Ftaylor_singletary
%2Fcallback", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1260811626",
oauth_consumer_key="dTgSkaRKZjEnS1vAUu6e7-
aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV",
oauth_signature="Ws%2B%2FH%2FonYnsZXyZwyEhgL
%2Bboq8s%3D", oauth_version="1.0"
Getting a Request Token

14. Evaluate the requestToken response
Now we issue this request to the requestToken endpoint, and if all is successful, you’ll get
something like the following URL encoded response:
oauth_token=f7868c3a-7336-4662-
a6d1-3219fb4650d1&oauth_token_secret=45e0ccd0-0c5
d-431e-831a-63f10552338a&oauth_callback_confirmed
=true
The oauth_token field is now your request token, and the oauth_token_secret will be used for
signing your request for an access token. oauth_callback_confirmed just gives you confirmation
that we recognized your oauth_callback parameter.
You’ll want to “hold on” to the oauth_token and oauth_token_secret until you’ve completed
the access token step.
Getting a Request Token

16. Build your authorization URL
Now that we have a request token, we can build the URL to authorize the user. We’ll then
redirect the user to this URL so they can grant your application access.
An authorization URL is simply this end point: https://api.linkedin.com/uas/oauth/authorize with
a query parameter tacked on called oauth_token. The value for this parameter is equal to the
request token you received in the previous step.
With this same example, you’d direct the user to this URL:
https://api.linkedin.com/uas/oauth/authorize?
oauth_token=f7868c3a-7336-4662-a6d1-3219fb4650d1
The user needs to land on this page within 5 minutes of your request token cycle. You should
not pass an oauth_callback parameter to this page (you already did that in the request token
step).
Authorizing the member

17. Send the user to LinkedIn’s Authorization Page
The user will then be sent to our authorization page. When completed the user will either be
sent back to your oauth_callback URL or presented with a series of digits they’ll be instructed
to hand-enter into your application (if you are performing out-of-band authentication).
Authorizing the member

18. OAuth Callback vs. Out of Band
After authorizing your application, the After authorizing your application, the
user will be sent to the URL you specified member is presented with a PIN code.
as the oauth_callback.
Your callback will receive In your application, you
an oauth_token and should now present a UI
oauth_token_secret; these allowing the user to
are the same as your hand-enter the PIN
request tokens. code.
You’ll also receive an After receiving the PIN
oauth_verifier parameter, code, you’ll be using it
which you will need to for the accessToken step
attach as part of your as the oauth_verifier.
accessToken request in the
next step.

19. Exchanging a request token for an access token.

20. Prepare your signing secret
Regardless of whether you used out-of-band authentication or not, you’ll now be equipped with
a request token, an oauth_token_secret, and an oauth_verifier. You’re now going to exchange
that request token for an access token, imbued with the permission of the LinkedIn member to
act on their behalf.
In LinkedIn’s strict OAuth implementation, a request for an access token must be signed using
both your consumer secret and the oauth_token_secret you received as when retrieving your
request token. Many existing OAuth libraries do not properly incorporate the
oauth_token_secret in this step.
Your signing key will be in the format of:
url_escape(consumer_secret)&url_escape(oauth_token_secret)
Getting an Access Token

21. Now build your string to sign.
We’ll use these values for this example. Your oauth_token is your requestToken.
HTTP Method POST
Request URI https://api.linkedin.com/uas/oauth/accessToken
oauth_consumer_key dTgSkaRKZjEnS1vAUu6e7-aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV
oauth_nonce WqKwyyrjQLgpaeJIB6MWKKmDOIpxKBrz0lLabSO3UI
oauth_signature_method HMAC-SHA1
oauth_timestamp 1260811635
oauth_token f7868c3a-7336-4662-a6d1-3219fb4650d1
oauth_verifier 75553
oauth_version 1.0
Getting an Access Token

22. Now build your string to sign.
These parameters get sorted alphabetically, each value is URL escaped, and than
concatenated into a single string.
POST&https%3A%2F%2Fapi.linkedin.com%2Fuas%2Foauth
%2FaccessToken&oauth_consumer_key
%3DdTgSkaRKZjEnS1vAUu6e7-aYC00UilBTwnXHpLH7NyL2e-
klzBC1a4TKCnSgClWV%26oauth_nonce
%3DWqKwyyrjQLgpaeJIB6MWKKmDOIpxKBrz0lLabSO3UI
%26oauth_signature_method%3DHMAC-
SHA1%26oauth_timestamp%3D1260811635%26oauth_token
%3Df7868c3a-7336-4662-
a6d1-3219fb4650d1%26oauth_verifier
%3D75553%26oauth_version%3D1.0
Getting an Access Token

23. Create your Authorization HTTP Header & Issue the Request
Now we sign this string using the secret we constructed from our consumer secret and
oauth_token_secret, then create an HTTP Authorization header, including the signature as the
oauth_signature value, and oauth_nonce, oauth_callback, oauth_signature_method,
oauth_timestamp, oauth_consumer_key, oauth_token, oauth_verifier, and oauth_version.
Authorization: OAuth
oauth_nonce="WqKwyyrjQLgpaeJIB6MWKKmDOIpxKBrz0lLabSO3
UI", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1260811635",
oauth_consumer_key="dTgSkaRKZjEnS1vAUu6e7-
aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV",
oauth_token="f7868c3a-7336-4662-a6d1-3219fb4650d1",
oauth_verifier="75553",
oauth_signature="gp3C1jCOgRyN106UIe0FLTzOmu8%3D",
oauth_version="1.0"
Getting an Access Token

24. Evaluate the accessToken response
Now we issue this request to the accessToken endpoint, and if all is successful, you’ll get
something like the following URL encoded response:
oauth_token=fb74aed1-
eb7d-4f3f-855c-137000243df8&oauth_token_secret=4e7f56
2d-04b1-4488-8162-95a2454ae9a8
The oauth_token field is now your access token, and the oauth_token_secret will be used for
signing all requests on behalf of the member.
You’ll want to “hold on” to the oauth_token and oauth_token_secret for as long as you want to
act on the member’s behalf.
A LinkedIn member may specify that an access token is valid only for a certain period of time
(or forever), but can revoke access on LinkedIn.com at any time.
Getting an Access Token

25. You’ve acquired an access token!
But don’t hang up your dancing shoes yet.

26. LinkedIn is about people.
LinkedIn is about you.

27. Making API resource requests is very similar to other operations. You’ll need your access
token, oauth_token_secret, and your API keys to continue.
We’re going to ask for our own profile from LinkedIn’s people resource. In LinkedIn resource
URLs, the tilde (“~”) character represents the member associated with your access token.
LinkedIn’s API works best when you explicitly tell it what you are looking for, so we’re asking for
the member’s id, first name, last name, and their headline only.
The resource URL for this request would be:
When URL encoding this resource in the following OAuth signing steps, you’ll want to ensure
that the tilde character does not become escaped. The field selectors are not query
parameters, but part of the path of the URI itself.
Requesting your own profile

28. Start by building your string to sign.
We’ll use these values for this example. Your oauth_token is your access token.
HTTP Method GET
Request URI https://api.linkedin.com/v1/people/~:(id,first-name,last-name,headline)
oauth_consumer_key dTgSkaRKZjEnS1vAUu6e7-aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV
oauth_nonce Tv4o9eX4Dmui9uW5otBVweTI28O0YmIWPnRhu0XhmY
oauth_signature_method HMAC-SHA1
oauth_timestamp 1260915816
oauth_token fb74aed1-eb7d-4f3f-855c-137000243df8
oauth_version 1.0
Requesting your own profile

29. Start by building your signature base string.
These parameters get sorted alphabetically, each value is URL escaped, and than
concatenated into a single string.
GET&https%3A%2F%2Fapi.linkedin.com%2Fv1%2Fpeople%2F~
%3A%28id%2Cfirst-name%2Clast-name%2Cheadline
%29&oauth_consumer_key%3DdTgSkaRKZjEnS1vAUu6e7-
aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV
%26oauth_nonce
%3DTv4o9eX4Dmui9uW5otBVweTI28O0YmIWPnRhu0XhmY
%26oauth_signature_method%3DHMAC-
SHA1%26oauth_timestamp%3D1260915816%26oauth_token
%3Dfb74aed1-
eb7d-4f3f-855c-137000243df8%26oauth_version%3D1.0
Requesting your own profile

30. Create your Authorization HTTP Header & Issue the Request
Now we sign this string using our consumer secret in conjunction with your access token’s
oauth_token_secret (just like in our previous steps) and create an HTTP Authorization header,.
The signature should be included as the oauth_signature value.
Authorization: OAuth
oauth_nonce="Tv4o9eX4Dmui9uW5otBVweTI28O0YmIWPnRhu0Xh
mY", oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1260915816",
oauth_consumer_key="dTgSkaRKZjEnS1vAUu6e7-
aYC00UilBTwnXHpLH7NyL2e-klzBC1a4TKCnSgClWV",
oauth_token="fb74aed1-eb7d-4f3f-855c-137000243df8",
oauth_signature="4imDw81fRdCI%2FBBoo0vwix5giVo%3D",
oauth_version="1.0"
Requesting your own profile

31. Evaluate the XML response
Now we issue this request to the people resource, and if all is successful, you’ll get something
like the following XML response, with your own profile values in place of my own.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person>
<id>esIpa2xh0v</id>
<first-name>Taylor</first-name>
<last-name>Singletary</last-name>
<headline>Technical Evangelist at LinkedIn</headline>
</person>
If the access token is invalid, or your signature was not properly calculated, you will receive a
401 Unauthorized error. There is always interesting debugging information in the XML body of
a failed request and the HTTP headers we return to you. Maybe your timestamp was off by a
few minutes? Maybe your signature was invalid? Maybe the access token is no longer valid?
Requesting your own profile

32. Troubleshooting

33. OAuth is complicated, and there are a number of things that go wrong.
Here are some tips.
Every error response we send you will contain an XML body describing the error, including a
timestamp representing API server time. Some OAuth-based requests will also return an
oauth_problem HTTP header.
Make sure that your server’s system clock is in sync with ours.
oauth_callback should only be provided on the requestToken step.
oauth_verifier is required in the accessToken step.
PUT & POST operations typically have XML Content-Types. Your OAuth library should
exclude the request body in signature calculations as a result.
For the access token step, remember that the request token’s oauth_token_secret must be
used as part of your signing key.
Likewise, for API resource requests, your access token’s oauth_token_secret must be used as
part of your signing key.
At this time, LinkedIn only supports HTTP header-based OAuth. Make sure that you are
passing your OAuth credentials as an Authorization HTTP header, not as query parameters
attached to the request.
Troubleshooting

34. Working with LinkedIn’s OAuth
OAuth Authentication
Common Issues with OAuth Authentication
General OAuth
OAuth 1.0a Spec
Beginner’s Guide to OAuth
Client Libraries
& Community Code
Ruby
PHP
Java
.NET
Further Reading

35. I hope you had the time of your life mastering the OAuth dance.
Thanks to all the great people in the LinkedIn Developer Community!