csharp
java
javascript
php
python
ruby
typescript

oauth

/oauth

OAuth guide

UltraCart allows you to build applications that communicate with the UltraCart service on behalf of users. You will need to have each use authenticate, verify their identity, with UltraCart and then grant permission to your application 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'll need to send with each subsequent API request to uniquely identify both your application and the end user.

There are several important benefits that lead us to select OAuth:

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

Setting up your application

Before you can get started, you'll need to register your application with UltraCart under:

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

Under this management screen you will be able to configure the application name, developer information, redirect URL, and permissions.

After creating your application, you are ready to set-up the authorization process in your application. The UltraCart SDKs contain the API methods below to assist in the OAuth flow.

OAuth 2 flow

Here's a simple diagram of the OAuth 2 flow - the process for authorizing your users with UltraCart.

User App: Load my item information from UltraCart.

App UltraCart: User would like to load item information from UltraCart

UltraCart User: User would like allow the application to load your item information?

User UltraCart: Yes, allow the application access to my item information

The Application and UltraCart can now send and recieve the users item information.

The high level idea is that the user will be redirected to UltraCart to authorize your application to access their UltraCart data. After the user has approved your application, they'll be sent back to your application with an authorization code. At this point your application will exchange the authorization code for an access token which can be used to make subsequent requests to the UltraCart API (not shown in the diagram above).

  1. User presses a “Connect” button
  2. Your App redirects the user to a UltraCart webpage. /oauth2/authorize?response_type=code
  1. The user logs into UltraCart and authorizes your app
  2. UltraCart redirects the user back to your app using the redirect_uri you provided.
  1. Your app exchanges the authorization code for a reusable access token (not visible to the user).

If you're building a web application, the first step in the OAuth process is to redirect the user to an UltraCart web page. Typically the user takes some action on your site, such as clicking a "Connect to UltraCart" button, and your application will need to redirect the user to a particular UltraCart authorization URL.

The UltraCart authorization URL is specific to your application and is 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). The complete /authorize URL is documented below. You will need to generate this complete URL and have the user click on it to start the process. Make sure you are careful about properly URL encoding each parameter value when building the URL.

At this point in the flow, the user will need to login to UltraCart. Once the user is logged into UltraCart, they will be presented with a screen to authorize your application to access their UltraCart data.

TODO: UltraCart authorize screen

After the user approves your application, they'll be redirected from UltraCart back to your application using the redirect URI provided in the application configuration or UltraCart authorization URL. For security, this redirect URI must match one of the redirect URIs you have specified for your application and also contain a secret state parameter which will be returned in the redirect.

The redirect back to your application will include an authorization code from UltraCart. Your application will then need to exchange the authorization code for a re-usable access token immediately. The exchange takes place in the background of your application using a call to the /token API documented below.

The access token is the important credential that is needed to make successful UltraCart API calls. You'll want to store this within your application securely and it should not be displayed to the end user.

Now your application is authorized to use the UltraCart API on behalf of your user. When you'd like to make API calls to UltraCart, simply include the authorization header, Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>, with each request.




using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using NUnit.Framework;

namespace SdkSample.oauth
{
    public class Introduction
    {

        [Test]
        public void ExecuteTest()
        {
            //TODO-PT
        }

        public static void IntroductionCall()
        {
            const string simpleKey = "109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00";
            var api = new OauthApi(simpleKey);
        }


    }
}




package oauth;

import com.ultracart.admin.v2.OauthApi;
import com.ultracart.admin.v2.models.Coupon;
import com.ultracart.admin.v2.models.CouponResponse;
import com.ultracart.admin.v2.util.ApiException;

public class Introduction {

    public static void main(String[] args) throws ApiException {

        // Create a Simple Key: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/38688545/API+Simple+Key
        final String apiKey = "109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00";
        OauthApi oauthApi = new OauthApi(apiKey);

        // TODO-PT

    }

}

Authorize an application

get
/oauth/authorize

The link that a customer must click on to begin the authorization process. This is not an API call that you can make from your application, but is a link that you need to construct and then have your user click on it to authorize your application.

SDK Function Name: oauthAuthorize

Parameters
Parameter Description Location Data Type Required
client_id The OAuth application client_id. query string required
redirect_uri The URL to redirect the users browser back to once authorization is granted. This can only be specified if the application profile does not include a pre-configured redirect_uri. query string optional
scope The permission scope requested. This can only be specified if the application profile does not include a pre-configured scope. query string optional
state A unique value generated by your application to assist in authenticating the redirect back. query string required
response_type Type of response
Allowed Values
  • code
 query string required
Responses
Status Code Reason Response Model
307
 Temporary Redirect 307
400
 Bad Request 400
403
 Forbidden 403
404
 Not Found 404
500
 Server Side 500 



using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using NUnit.Framework;

namespace SdkSample.oauth
{
    public class OauthAuthorize
    {

        [Test]
        public void ExecuteTest()
        {
            //TODO-PT
        }

        public static void OauthAuthorizeCall()
        {
            const string simpleKey = "109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00";
            var api = new OauthApi(simpleKey);
        }


    }
}




package oauth;

import com.ultracart.admin.v2.OauthApi;
import com.ultracart.admin.v2.models.Coupon;
import com.ultracart.admin.v2.models.CouponResponse;
import com.ultracart.admin.v2.util.ApiException;

public class OauthAuthorize {

    public static void main(String[] args) throws ApiException {

        // Create a Simple Key: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/38688545/API+Simple+Key
        final String apiKey = "109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00";
        OauthApi oauthApi = new OauthApi(apiKey);

        // TODO-PT

    }

}

Revoke this OAuth application.

Consumes: application/x-www-form-urlencoded
Produces: application/json
post
/oauth/revoke

Revokes the OAuth application associated with the specified client_id and token.

SDK Function Name: oauthRevoke

Parameters
Parameter Description Location Data Type Required
client_id The OAuth application client_id. formData string required
token The OAuth access token that is to be revoked.. formData string required
Responses
Status Code Reason Response Model
200
 Successful response OauthRevokeSuccessResponse
400
 Bad Request 400
500
 Server Side 500 



using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using NUnit.Framework;

namespace SdkSample.oauth
{
    public class OauthRevoke
    {

        [Test]
        public void ExecuteTest()
        {
            //TODO-PT
        }

        public static void OauthRevokeCall()
        {
            const string simpleKey = "109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00";
            var api = new OauthApi(simpleKey);
        }


    }
}




package oauth;

import com.ultracart.admin.v2.OauthApi;
import com.ultracart.admin.v2.models.Coupon;
import com.ultracart.admin.v2.models.CouponResponse;
import com.ultracart.admin.v2.util.ApiException;

public class OauthRevoke {

    public static void main(String[] args) throws ApiException {

        // Create a Simple Key: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/38688545/API+Simple+Key
        final String apiKey = "109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00";
        OauthApi oauthApi = new OauthApi(apiKey);

        // TODO-PT

    }

}

Exchange authorization code for access token.

Consumes: application/x-www-form-urlencoded
Produces: application/json
post
/oauth/token

The final leg in the OAuth process which exchanges the specified access token for the access code needed to make API calls.

SDK Function Name: oauthAccessToken

Parameters
Parameter Description Location Data Type Required
client_id The OAuth application client_id. formData string required
grant_type Type of grant
Allowed Values
  • authorization_code
  • refresh_token
 formData string required
code Authorization code received back from the browser redirect formData string required if
grant_type=authorization_code
redirect_uri The URI that you redirect the browser to to start the authorization process formData string required if
grant_type=authorization_code
refresh_token The refresh token received during the original grant_type=authorization_code that can be used to return a new access token formData string required if
grant_type=refresh_token
Responses
Status Code Reason Response Model
200
 Successful response OauthTokenResponse
400
 Bad Request 400
500
 Server Side 500 



using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;
using NUnit.Framework;

namespace SdkSample.oauth
{
    public class OauthAccessToken
    {

        [Test]
        public void ExecuteTest()
        {
            //TODO-PT
        }

        public static void OauthAccessTokenCall()
        {
            const string simpleKey = "109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00";
            var api = new OauthApi(simpleKey);
        }


    }
}




package oauth;

import com.ultracart.admin.v2.OauthApi;
import com.ultracart.admin.v2.models.Coupon;
import com.ultracart.admin.v2.models.CouponResponse;
import com.ultracart.admin.v2.util.ApiException;

public class OauthAccessToken {

    public static void main(String[] args) throws ApiException {

        // Create a Simple Key: https://ultracart.atlassian.net/wiki/spaces/ucdoc/pages/38688545/API+Simple+Key
        final String apiKey = "109ee846ee69f50177018ab12f008a00748a25aa28dbdc0177018ab12f008a00";
        OauthApi oauthApi = new OauthApi(apiKey);

        // TODO-PT

    }

}

Error

Attributes
Name Data Type Description
developer_message string A technical message meant to be read by a developer
error_code string HTTP status code
more_info string Additional information often a link to additional documentation
object_id string Object id that the error is associated with
user_message string An end-user friendly message suitable for display to the customer

ErrorResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

OauthRevokeSuccessResponse

Attributes
Name Data Type Description
message string Message confirming revocation of credentials
successful boolean True if revoke was successful

OauthTokenResponse

Attributes
Name Data Type Description
access_token string Access token to use in OAuth authenticated API call
error string
error_description string
error_uri string
expires_in string The number of seconds since issuance when the access token will expire and need to be refreshed using the refresh token
refresh_token string The refresh token that should be used to fetch a new access token when the expiration occurs
scope string The scope of permissions associated with teh access token
token_type string Type of token
Allowed Values
  • bearer

ResponseMetadata

Attributes
Name Data Type Description
payload_name string Payload name
result_set ResultSet Result set

ResultSet

Attributes
Name Data Type Description
count integer (int32) Number of results in this set
limit integer (int32) Maximum number of results that can be returned in a set
more boolean True if there are more results to query
next_offset integer (int32) The next offset that you should query to retrieve more results
offset integer (int32) Offset of this result set (zero based)
total_records integer (int32) The total number of records in the result set. May be null if the number is not known and the client should continue iterating as long as more is true.

Warning

Attributes
Name Data Type Description
more_info string Additional information often a link to additional documentation
warning_message string A technical message meant to be read by a developer

307
Status Code 307: Temporary redirect to follow

Headers
Name Data Type Description
Location string The URL to redirect to

400
Status Code 400: bad request input such as invalid json

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

403
Status Code 403: forbidden

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

404
Status Code 404: not found

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

500
Status Code 500: any server side error. the body will contain a generic server error message

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse