Authcode Grant Type

Use cases: Integrating UPS APIs into your software for many entities within your business or for other entities. Because you, the software provider, will not know (not have access) the UPS ID credentials – the authcode flow is used to let your software customer use their UPS information within your application in a simple and secure way.

Setup Required: When you setup your application, you will need to enter your CallbackURL. This can be found on your application details page under Callback URL.

Note: Different endpoints will be used for Authcode flow vs Client credential flow

How to implement:

1. Once you have the setup completed and a user is needing to connect their UPS Account, make a first call to the OAuth endpoint with your application's client_id and redirect_uri

   curl --location --request GET 'https://wwwcie.ups.com/security/v1/oauth/validate-client?client_id=testClientID&redirect_uri=https://testapplication.com'

   1. Receive UPS Login page URL (LassoRedirectURL)

   {​​​​​
       "result": "success",
       "type": "ups_com_api",
       "LassoRedirectURL": "https://www.ups.com/lasso/signin"
   }​​​​​

2. Your application should redirect the user to the UPS login screen, with the LassoRedirectURL in addition to a few query parameters.
   1. Required Parameters: client_id, redirect_uri, response_type, scope, and type
      1. The client_id and redirect_uri should be your application's information.
      2. The type will be the type returned in the validate-client call from Step 1.
      3. The response_type and scope will both be static values.

   https://www.ups.com/lasso/signin?client_id=testClientID&redirect_uri=https://testapplication.com&response_type=code&scope=read&type=ups_com_api

3. The user will enter the login credentials on the redirected UPS login screen.
4. The UPS login screen will redirect the user back to your application's indicated redirect_uri.
   1. Your application must retrieve the user's Auth-Code from the redirected URL's query parameter code. 

   https://testapplication.com?code=[Auth-Code]&scope=

5. Your application should now retrieve an access token on behalf of the user using your application's client id and secret.

   Request:

   curl --location --request POST 'https://wwwcie.ups.com/security/v1/oauth/token' \
   --header 'Authorization: Basic R0tWbldUOTFqaUpWc1ZCQWl6R0owcWlzNnpKcVhvRVk3NFJG=' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=authorization_code' \
   --data-urlencode 'code=[Auth-Code]'
   --data-urlencode 'redirect_uri=https://testapplication.com'

   Response:

   {​​​​​
       "refresh_token_expires_in": "604799",
       "refresh_token_status": "approved",
       "token_type": "Bearer",
       "issued_at": "1662558626563",
       "client_id": "testClientID",
       "access_token": "access_token",
       "refresh_token": "refresh_token",
       "scope": "",
       "refresh_token_issued_at": "1662558626563",
       "expires_in": "14399",
       "refresh_count": "0",
       "status": "approved"
   }​​​​​

6. Your application can utilize the access_token to make API calls on behalf of the user.
7. The access_token has a limited lifespan, and must be refreshed using the refresh_token from Step 5. Your application should refresh the access token if an unauthenticated error is returned for API call, or if the token is approaching the expiry time returned in Step 5. 

   Request:

   curl --location --request POST 'https://apis-pt.ups.com/security/v1/oauth/refresh' \
   --header 'Authorization: Basic R0tWbldUOTFqaUpWc1ZCQWl6R0owcWlzNnpKcVhvRVk3NFJG=' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=refresh_token' \
   --data-urlencode 'refresh_token=[refresh-token]'

   Response:

   {​​​​​
       "refresh_token_expires_in": "604738",
       "refresh_token_status": "approved",
       "old_access_token_life_time": "61228",
       "token_type": "Bearer",
       "issued_at": "1662558687774",
       "client_id": "testClientID",
       "access_token": "access_token",
       "refresh_token": "refresh_token",
       "scope": "",
       "refresh_token_issued_at": "1662558626563",
       "expires_in": "2591999",
       "refresh_count": "3",
       "status": "approved"
   }​​​​​