Authorization Code Flow (3-legged OAuth)
The Authorization Code Flow is used for applications to request permission from a Passport member to access their account data. The level of access or profile detail is explicitly requested using the scope parameter during the authorization process outlined below. This workflow will send a consent prompt to a selected member, and once approved your application may begin making API calls on behalf of that member.
This approval process ensures that Passport members are aware of what level of detail an application may access or action it may perform on their behalf.
If multiple scopes are requested, the user must be consent to all of them and may not select individual scopes. For the benefit of your Passport users, please ensure that your application requests the least number of scope permissions.
Authorization Code Flow
Configure your application in the Developer Portal to obtain Client ID and Client Secret.
Your application directs the browser to Passport's OAuth 2.0 authorization page where the member authenticates.
After authentication, Passport's authorization server passes an authorization code to your application.
Your application sends this code to Passport and Passport returns an access token.
Your application uses this token to make API calls on behalf of the member.
Prerequisites
Have a Passport Developer application to create a new application or select your existing application
Have prior authorization access granted for at least one 3-legged OAuth permission.
The permission request workflow is outlined in the Getting Access section.
Request an Authorization Code
To request an authorization code, you must direct the member's browser to Passport's OAuth 2.0 authorization page, where the member either accepts or denies your application's permission request.
Once the request is made, one of the following occurs:
If it is a first-time request, the permission request timed out, or was manually revoked by the member: the browser is redirected to Passport's authorization consent window.
If there is an existing permission grant from the member: the authorization screen is bypassed and the member is immediately redirected to the URL provided in the redirect_uri query parameter.
When the member completes the authorization process, the browser is redirected to the URL provided in the redirect_uri query parameter.
Note If the scope permissions are changed in your app, your users must re-authenticate to ensure that they have explicitly granted your application all of the permissions that it is requesting on their behalf.
response_type
string
The value of this field should always be: code
Yes
client_id
string
The API Key value generated when you registered your application.
Yes
redirect_uri
url
Yes
state
string
No
scope
string
Yes
Sample Request
Once redirected, the member is presented with Passport's authentication screen. This identifies your application and outlines the particular member permissions/scopes that your application is requesting.
Member Approves Request
By providing valid Passport credentials and clicking Allow, the member approves your application's request to access their member data and interact with Passport on their behalf. This approval instructs Passport to redirect the member to the redirect URL that you defined in your redirect_uriparameter.
Attached to the redirect_uri are two important URL arguments that you need to read from the request:
code — The OAuth 2.0 authorization code.
state — A value used to test for possible CSRF attacks.
The code is a value that you exchange with Passport for an OAuth 2.0 access token in the next step of the authentication process. For security reasons, the authorization code has a 30-minute lifespan and must be used immediately. If it expires, you must repeat all of the previous steps to request another authorization code.
Warning
Before you use the authorization code, your application should ensure that the value returned in the state parameter matches the state value from your original authorization code request. This ensures that you are dealing with the real member and not a malicious script. If the state values do not match, you are likely the victim of a CSRF attack and your application should return a 401 Unauthorized error code in response.
Failed Request
If the member chooses to cancel, or the request fails for any reason, the client is redirected to your redirect_uri with the following additional query parameters appended:
error - A code indicating one of these errors: user_cancelled_login - The member declined to log in to their Passport account. user_cancelled_authorize - The member refused to authorize the permissions request from your application. error_description - A URL-encoded textual description that summarizes the error. state - A value passed by your application to prevent CSRF attacks.
Exchange Authorization Code for an Access Token
The next step is to get an access token for your application using the authorization code from the previous step.
To do this, make the following HTTP POST request with a Content-Type header of x-www-form-urlencoded using the following parameters in the request body:
grant_type
string
The value of this field should always be: authorization_code
Yes
code
string
The authorization code you received in Step 2.
Yes
client_id
string
The Client ID value generated in Step 1.
Yes
client_secret
string
The Secret Key value generated in Step 1.
Yes
redirect_uri
url
The same redirect_uri value that you passed in the previous step.
Yes
Sample Request
Access Token Response
A successful access token request returns a JSON object containing the following fields:
access_token
string
expires_in
int
The number of seconds remaining until the token expires. Currently, all access tokens are issued with a 60-day lifespan.
Access Token Scopes and Lifetime
Access tokens stay valid until the number of seconds indicated in the expires_in field in the API response. You can go through the OAuth flow on multiple clients (browsers or devices) and simultaneously hold multiple valid access tokens if the same scope is requested. If you request a different scope than the previously granted scope, all the previous access tokens are invalidated.
Last updated