Skip to main content
Explanation

OAuth 2.0 Guide

UltraCart lets you build applications that communicate with the UltraCart service on behalf of users. Each user authenticates — verifies their identity with UltraCart — and then grants your application permission to access data on their UltraCart account.

UltraCart uses OAuth 2, an open specification, for third-party application authentication. Once a user completes the OAuth process, an access token is returned to your application. The access token is a long string generated by UltraCart that you send with each subsequent API request to uniquely identify both your application and the end user.

Several benefits led us to choose OAuth:

  • Most importantly, your application does not need to store or transmit the UltraCart user's password.
  • OAuth lets the user authorize a limited set of permissions to your application.
  • Users can revoke access to an individual application at any time.
  • The protocol is an industry (IETF) standard that has had multiple revisions and security reviews.

This makes OAuth a safer, more secure form of API authorization for your users.

tip

Building an in-house integration for a single account instead of a multi-merchant app? A Simple Key is simpler and more appropriate.

Setting up your application​

Before you can get started, register your application with UltraCart under:

Configuration -> Back Office -> Authorized Applications -> Developer Applications

From this management screen you configure the application name, developer information, redirect URL, and permissions. After creating your application, you're ready to set up the authorization process in your code. The UltraCart SDKs contain API methods to assist with the OAuth flow.

The OAuth 2 flow​

At a high level, the user is redirected to UltraCart to authorize your application to access their data. After they approve, they're sent back to your application with an authorization code, which your application exchanges for a reusable access token.

Step by step​

  1. Start the flow. Typically the user takes some action on your site, such as clicking a "Connect to UltraCart" button. Your application redirects the user to an UltraCart authorization URL specific to your application, composed of your client ID, redirect URI, response type, and state — it looks something like:

    https://secure.ultracart.com/admin/v2/oauth/authorize?client_id=...&redirect_uri=...&state=...&response_type=code

    Generate this complete URL and have the user click it to begin. Be careful to properly URL-encode each parameter value. The complete /authorize request is documented on the OAuth endpoints page.

  2. User logs in and approves. The user logs into UltraCart, then sees a screen to authorize your application to access their UltraCart data.

  3. Redirect back with a code. After the user approves, UltraCart redirects them back to your application using the redirect URI from your application configuration or authorization URL. For security, this redirect URI must match one of the redirect URIs specified for your application, and the redirect carries back the secret state parameter you sent. The redirect also includes an authorization code.

  4. Exchange the code for a token. Your application exchanges the authorization code for a reusable access token immediately, in the background, via a call to the /token endpoint.

  5. Call the API. The access token is the credential needed to make successful UltraCart API calls. Store it securely within your application — it should never be displayed to the end user. Include it as an authorization header on every request:

    Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>
warning

Treat the access token like a password. Store it securely server-side and never expose it to the end user or commit it to source control.

Was this page helpful?