Authorization Code


Use this authentication grant type for web-based scenarios. Possibly the most secure type of authorization since it is used by applications running on a web server that are capable of keeping a secret. This secret is not available to the public--it is secured server-side. 

OAuth 2.0 Authorization Code Grant Type Flow 

OAuth 2.0 Authorization Code Grant Type Flow


Example Flow

1. Send uShip user to uShip.com for authorization

 

The sign-in link below sends them to a uShip authorization page which is hosted on a uShip server and secures this OAuth2 flow.  For security, the redirect_uri above must be registered in the developer portal.  You can set your redirect_uri at https://developer.uship.com/apps/myapps.

 

Sign-in Link

https://www.uship.com/mvc/connect
?response_type=code
&client_id={{clientid}}
&redirect_uri={{httpsURI}}
&scope={{scope}}
 

 

 

2.  uShip user reviews and accepts 3rd party app requirements

After supplying their uShip username and password, the user can review the permissions (scopes) and choose to Deny or Allow authorization. This authorization gives the app the ability to act on behalf of a uShip user.

 

 

3.  Acquire the Authorization Code

The response will be sent to the redirect_uri as specified in the request from the first step. If the user approves the access request, then the response contains an authorization code in the query string along with scopes that were accepted.

 

 

4.  Redeem the Authorization Code for a Bearer Token

The bearer token is what allows your application to make calls on the uShip user's behalf.  Note that the authorization code has a short-lived TTL and should be immediately redeemed.

POST to the URL https://api.uship.com/oauth/token

Request

Header
content-type:ʉ۬application/x-www-form-urlencoded

code={{authcode}}
&grant_type=authorization_code
&client_id={{clientid}}
&client_secret={{secret}}
&redirect_uri={{httpsURI}}

 

Response

{
"token_type": "bearer",
"access_token": "string",
"expires_in": 2592000,
"refresh_token": "string",
"scope": "scope string"
}

 

 

5. Use the access token or call a uShip API.

 

 

6. Refresh the token as necessary.

While the refresh token is long-lasting (1 year), the Bearer token only lasts 10 minutes.  If the token expires, subsequent requests will result in a 403 reponse and body “Developer Inactive” and you'll need to perform another refresh.  For reference, here are Microsoft’s patterns for refresh logic:  https://msdn.microsoft.com/en-us/library/hh454950.aspx

POST to the URL https://api.uship.com/oauth/token

Request

Header
content-type:ʉ۬application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={{clientid}}
&client_secret={{client_secret}}
&refresh_token={{refresh_token}}

 

Response

{
"token_type": "bearer",
"access_token": "string",
"expires_in": 2592000,
"refresh_token": "string",
"scope": "scope string"
}