Authentication

Our APIs support two primary methods of authentication:

• OAuth 2.0
• Simple Key

OAuth 2.0 authentication is the industry-standard way of authenticating a third-party application, such as a plugin, to an UltraCart account with a limited set of permissions. If you're developing an application that is going to be used by multiple merchants, then OAuth 2.0 authentication is appropriate.

Simple key authentication is exactly what it sounds like: a simple key generated by the system that is useful for authenticating API calls for your organization. If you're developing an in-house application to automate interactions with UltraCart, then simple key authentication is the appropriate mechanism to use.

All of the client libraries generated for the UltraCart REST API support both methods of authentication.

OAuth 2.0

Authenticating with OAuth 2.0 involves having the end user click the authorization link. The URL contains the client ID for your Developer Application, redirect information (optional), the request type of code, and a random number. When the user clicks the link, they are taken to the UltraCart login page. The user must log in first, then they are shown a page about your application and the permissions it is requesting, and are given the chance to approve or deny it. If they approve the application, their browser is redirected to a page that takes the code parameter from the URL and then calls the OAuth /token REST API to exchange the temporary authorization code for a more permanent access token.

For a full walkthrough — registering your application and the complete authorization-code flow — see the OAuth 2.0 Guide. The /authorize and /token endpoints themselves are documented in the OAuth reference.

Simple Key

The simple key authentication is by far the simplest. When you create a new application under:

Configuration -> Back Office -> Authorized Applications

and choose simple key as your authentication scheme, a very long key is generated for your application to use. This key is easily specified when instantiating the API. If you're doing individual internal development, use this authentication scheme.

Security requirements

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

tip

If your application is running from a known IP address, we encourage you to also restrict API calls to that particular IP address as an added security measure.

note

Every request must also send the API version header. Requests without it will fail.