Authentication


OAuth 2.0

As developers, we know it's best practice not to ask users for their credentials. OAuth authentication is useful for automated app connections and utilizes security measures the spec was designed to address.


uShip APIs use the OAuth 2.0 protocol for authentication and authorization. "OAuth is often described as a valet key for the web. It can be thought of as a special key that allows access to limited features and for a limited period of time without giving away full control, just as the valet key for a car allows the parking attendant to drive the car for a short distance, blocking access to the trunk and the on-board cell phone." - Agraj Mangal

Four major flows are covered on this page. Click on the specific grant flow type for detailed request and response models.

Basic Steps

  1. Obtain OAuth2 credentials on developer.uship.com.
  2. Use the credentials to get an access token that's right for your implementation.
  3. Use the access token to make API requests.
  4. Refresh the access token when necessary.

Headers Required for Authorization

Depends on the flow type

Header Value Description
Accept
application/json Acceptable Content-Types for the response.
Authorization
Bearer {access token} Required for every call after initial authorization. The "Bearer" label is case sensitive. There must be a space between this authorization label and the access token string.
Content-Type
application/json For POST and PUT requests, this header defines the request body's MIME type.
Content-Type
application/x-www-form-urlencoded Required for use with POSTs to obtain codes or tokens from an authorization or resource server.

 

Authorization Grant Types


We use Mashery as our secure token generator. 

A. Authorization Code

Use this type for web-based scenarios. Possibly the most secure type of authorization since it is used by applications running on a web server. The source code is not available to the public--written in a service-side language and run on a private server. 

B. Implicit

Best for single page JavaScript applications that require less security. Use for browser-based or mobile applications except for when you need a more secure method where we recommend the authorization code grant type.

C. Resource Owner Password Credentials

Use this grant type for scenarios where you want to authorize an app that needs access to a uShip user where they would supply their own credentials.

D. Client Credentials

Use this type if you are building an application that just needs to access an endpoint as an anonymous user. For example, there's no need for a specific user to search listings. You will need a client secret that must be handled in a secure fashion according to the OAuth 2.0 spec.

 

 

Set Up


  1. The uShip Account Manager or General Manager approves access to uShip's API and communicates this to the API Team. 
  2. The API Team grants access for you or your designated technical contact to use the API.
  • We cover which authentication type to code for when providing your website or application access to the uShip API via one of the four OAuth 2.0 flows.
  • Use the OAuth 2.0 grant types depending on the use case for v2 endpoints. We grant access to the resources that make the most sense for your integration needs. 
  • Unless you're only implementing the Shipping Price Estimates API, we have you test calls in the staging environment as the first step.
  • Specific instructions for your integration will be emailed to you. The API Support Team (api-support@uship.com) will work closely with you to get you up and running.

 

Sample App iOS OAuth 2.0 

http://commons.forgerock.org/samples/mobile/ios/openam-ios-oauth2-sample-app/

 

 

Resources


Source Credits

http://tools.ietf.org/pdf/rfc6749.pdf

http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified

http://code.tutsplus.com/articles/oauth-20-the-good-the-bad-the-ugly--net-33216

Image Credits

http://hueniverse.com/wp-content/uploads/2010/05/OAuth2.png