bannerColor WARNING_YELLOW templateName stackForums

Authentication

Overview

Follow the few easy steps below to make your first LinkedIn API call using OAuth 2.0.

We expect most new developers will prefer using OAuth 2.0 to implement authorization with LinkedIn APIs. Compared to its predecessor, OAuth 1.0a, the protocol is simpler and much easier to implement. However, for those applications that still need to support it, we do continue to provide legacy support for OAuth 1.0a.

Steps to Authenticate User

Step 1. Register your application
Register your application with LinkedIn. Specify a list of OAuth 2 redirect URLs by submitting a comma separated list of absolute URLs for your redirections else your requests to generate OAuth 2 tokens (Step 3 below) will fail. We strongly encourage using HTTPS.

Step 2. Save your API Key and Secret Key
After registration, you will receive a unique API Key and a Secret Key. API Key helps us identify your application and lets you make API calls. For the safety of your application please do not share your Secret Key.

Step 3. Get an access token
Access token is unique to a user and an API Key. You need access tokens in order to make API calls to LinkedIn on behalf of the user who authorized your application. Follow the two steps below to get one:

a. Generate Authorization Code by redirecting user to LinkedIn's authorization dialog

Redirect

https://www.linkedin.com/uas/oauth2/authorization?response_type=code
                                           &client_id=YOUR_API_KEY
                                           &scope=SCOPE
                                           &state=STATE
                                           &redirect_uri=YOUR_REDIRECT_URI

Make sure that you are using https for the request or you will get an error.

Parameter Description Possible Errors
response_type Required. Value is always code Passed a value other than code; Passed an empty value; Missing the parameter.
client_id Required. Value of your API Key given when you registered your application with LinkedIn Invalid client id; Passed multiple client ids; Passed an empty value; Missing the parameter
scope Optional. Use it to specify a list of member permissions that you need and these will be shown to the user on LinkedIn's authorization form. If not passed, defaults to r_ basicprofile. Specify multiple scopes by adding a space between different parameters. Remember to URL encode your spaces! Example: scope=r_fullprofile%20r_emailaddress%20r_network. Not spelled correctly or Invalid Value; Repeated scope values.
state Required. A long unique string value of your choice that is hard to guess. Used to prevent CSRF. Example: state=DCEEFWF45453sdffef424 Passed an empty value; Missing the parameter
redirect_uri Required. URI in your app where users will be sent after authorization. URI can use http or https. Example: http://www.mycoolsite.com Passed an invalid value; Passed an empty or blank value; Missing the parameter

If you see error "Invalid redirect_uri. This value must match a URL registered with the API Key.", then register your OAuth 2 redirect URLs as explained in Step 1.

If the user authorizes your application they will be redirected to the redirect_uri that you specified in your request above along with a temporary authorization_code and the same state that you passed in the request above.

Upon successful authorization, the redirected URL should look like:

YOUR_REDIRECT_URI/?code=AUTHORIZATION_CODE&state=STATE

Ensure that the state parameter in this response matches the one you passed in the authorization request above. If the state does not match, that means the request may be a result of CSRF and must be rejected.

If the user does not allow authorization to your application, redirection to the redirect_uri still occurs, with query parameters indicating the user canceled authorization and a short description of the error:

YOUR_REDIRECT_URI/?error=access_denied&error_description=the+user+denied+your+request&state=STATE

b. Request Access Token by exchanging the authorization_code for it

POST

https://www.linkedin.com/uas/oauth2/accessToken?grant_type=authorization_code
                                           &code=AUTHORIZATION_CODE
                                           &redirect_uri=YOUR_REDIRECT_URI
                                           &client_id=YOUR_API_KEY
                                           &client_secret=YOUR_SECRET_KEY

Make sure that you are using https for the request or you will get an error.

Parameter Description Possible Errors
grant_type Required. Value is always authorization_code Passed a value other than authorization_code; Passed an empty or blank value; Missing the parameter
code Required. Value of authorization_code that you got in the previous step. Passed invalid value; Authorization code expired; Passed an empty value; Missing the parameter
redirect_uri Required. Same redirect_uri that you passed in the previous step. Different redirect_uri than used during authorization code generation; Passed an invalid value; Passed an empty or blank value; Missing the parameter
client_id Required. Value of your API Key given when you registered your application with LinkedIn Different client-id than used during authorization code generation; Invalid client id; Passed multiple client ids; Passed an empty or blank value; Missing the parameter
client_secret Required. Value of your secret key given when you registered your application with LinkedIn Passed invalid value; Passed an empty value; Missing the parameter

The response will be a JSON object:

{"expires_in":5184000,"access_token":"AQXdSP_W41_UPs5ioT_t8HESyODB4FqbkJ8LrV_5mff4gPODzOYR"}

The value of parameter expires_in is the number of seconds from now that this access_token will expire in (5184000 seconds is 60 days). Please ensure to keep the user access tokens secure, as agreed upon in our APIs Terms of Use.

Step 4. Make an authenticated request
Now that you've successfully obtained an access token, you can start making authenticated API requests on behalf of the user. Our implementation calls for the access token to be passed with each API request using the HTTP Authorization header. Below is an example of a request to fetch the authenticated user's profile, along with the required HTTP headers:

1
2
3
4
GET /v1/people/~ HTTP/1.1
Host: api.linkedin.com
Connection: Keep-Alive
Authorization: Bearer AQXdSP_W41_UPs5ioT_t8HESyODB4FqbkJ8LrV_5mff4gPODzOYR

Note the last HTTP header in our example above. Here we set the header value of Authorization to "Bearer" + the access token fetched in the previous step. Ensure that the header value is formatted exactly as described above (with a space between the word "Bearer" and the access token) to avoid receiving a 401 Unauthorized error.

It's possible to make authenticated requests by passing the access token as a query parameter, but we strongly discourage doing so. It's an OAuth 2.0 security best practice to use the header-based authorization described above since query parameters could potentially get logged on your servers in log files (which may or may not be secure). For reference, here's an example of using the query parameter to make an authenticated request:

GET

https://api.linkedin.com/v1/people/~?oauth2_access_token=AQXdSP_W41_UPs5ioT_t8HESyODB4FqbkJ8LrV_5mff4gPODzOYR

All access tokens have a life span of 60 days. You should have a mechanism in your code to refresh the tokens before they expire in order to continue using the same access tokens. Otherwise you'll need to go through the authorization steps again. More details on how to handle expired tokens are explained on the next page.


Granting Member Permissions to Your Application

With the LinkedIn API, you have the ability to specify which permissions you want users to grant your application.

Member permissions provide the following:

  • Basic Profile default: When no permissions are specified, the basic profile permission will be used by default. Consider this to represent the current user’s ‘digital business card’.
  • All or None Grant: Members will need to accept all permissions requested by the application. Selection of individual permissions by the user is not supported.
  • Optimized for 3 Permissions: The user experience has been optimized for applications requesting 3 permissions. Requesting additional permissions are allowed, but not encouraged.
  • Re-Auth on Permission changes:A new login dialog will be presented to the user if different permissions are requested than what they initially granted.

Permission Scope Parameters
Requesting permissions from the user is straight forward. Pass the scopes you need granted as query parameters when redirecting the user to the /authorization endpoint. The following example asks for basic profile and email address permissions:

Alternatively, you may choose to specify which member permissions your application requests from the user without passing query parameters during authorization. You can easily configure this for your API key by visiting your application settings page and specify which scopes will be defaulted to the user in the Default scope section:

When the user is presented with the login dialog, LinkedIn shows the user the specific permissions you're asking for:

Below is a list of all member permissions

Permission Description Scope Primary Endpoints
Your Profile Overview Name, photo, headline, and current positions r_basicprofile GET /people/~
*see person field list
Your Full Profile Full profile including experience, education, skills, and recommendations r_fullprofile GET /people/~
*see person field list
Your Email Address The primary email address you use for your LinkedIn account r_emailaddress GET /people/~/email-address
Your Connections Your 1st and 2nd degree connections r_network GET /people/~/connections

GET /people/~/people-search
Your Contact Info Address, phone number, and bound accounts r_contactinfo GET /people/~

*see person field list
Network Updates Retrieve and post updates to LinkedIn as you rw_nus GET /people/~/network/updates

POST /people/~/shares
Company Page & Analytics Edit company pages for which I am an Admin and post status updates on behalf of those companies rw_company_admin POST /companies/{id}/shares

GETcompanies/{id}/company-statistics
Group Discussions Retrieve and post group discussions as you rw_groups GET & POST /groups

GET & POST /posts

GET & POST /people/~/group-memberships
Invitations and Messages Send messages and invitations to connect as you w_messages POST /people/~/mailbox

Security Best Practices

We've compiled a list of best practices to guide our developers when building applications on our platform. Please read and follow them to protect our mutual customers and their information.

Keeping Your Application Secure

By following the key points we've highlighted in our security best practices guide you can ensure that your application will be protected from some of the more common security vulnerabilities, such as having your API key/secret compromised or CSRF attacks.

Providing a Safe and Pleasant User Experience

In addition to keeping your application secure, it's also equally as important to develop your application in such a way that your intentions are transparent with your users. For example, requesting too many permissions from the user upon authorization or performing actions on unbeknownst to them create a bad user experience. Establish trust between your application and your users by following a few simple steps

Migrating from OAuth 1.0a to OAuth 2.0

If you're already happy with your current OAuth 1.0a solution, a migration to OAuth 2.0 isn't necessary. However, if you do decide to make the change, your current users who have already authorized your application won't need to be authorized again. As long as these users are already logged into LinkedIn:

  1. Your previously authorized user goes through the OAuth 2.0 flow as described above
  2. LinkedIn determines that this user has previously authorized your application and returns an auth code
  3. Since user has already authorized, a redirect isn't required. Instead, simply upgrade the auth code for an access token
  4. Your application now has a valid OAuth 2.0 access token

Provided that the user is already logged into LinkedIn, this flow provides you with a simple way of obtaining a valid OAuth 2.0 access token without forcing your user to authorize your application again