csharp
java
javascript
php
python
ruby
typescript

sso

/sso

Authorize a single sign on session

Permissions:
  • sso_write

Consumes: application/json
Produces: application/json
put
/sso/authorize

Starts the process of authorizing a single sign on session.

SDK Function Name: ssoAuthorize

Parameters
Parameter Description Location Data Type Required
authorization_request Authorization request body SingleSignOnAuthorizeRequest required
Responses
Status Code Reason Response Model
200
 Successful response SingleSignOnAuthorizeResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

Revoke single sign on session

Permissions:
  • sso_write

Produces: application/json
delete
/sso/session/revoke

This is the equivalent of logging out of the single sign on session

SDK Function Name: ssoSessionRevoke

Responses
Status Code Reason Response Model
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

Get single sign on session user

Permissions:
  • sso_write

Produces: application/json
get
/sso/session/user

This is the equivalent of logging out of the single sign on session

SDK Function Name: getSsoSessionUser

Responses
Status Code Reason Response Model
200
 Successful response User
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

Exchange a single sign on code for a simple key token

Permissions:
  • sso_write

Consumes: application/json
Produces: application/json
put
/sso/token

Called by your application after receiving the code back on the redirect URI to obtain a simple key token to make API calls with

SDK Function Name: ssoToken

Parameters
Parameter Description Location Data Type Required
token_request Token request body SingleSignOnTokenRequest required
Responses
Status Code Reason Response Model
200
 Successful response SingleSignOnTokenResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500

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

LinkedAccount

Attributes
Name Data Type Description
company (read only) string The company name of this linked account.
merchant_id (read only) string A merchant id that is linked to this account.
selected boolean If true, this user configuration (permissions, notifications, everything) is cascaded to this linked account.

Notification

Attributes
Name Data Type Description
can_filter_by_distribution_centers (read only) boolean True if this notification can be filtered to only send for one or more distribution centers.
can_include_affiliate (read only) boolean True if this notification can include an affiliate information.
can_include_order (read only) boolean True if this notification can include an order attachment.
can_include_order_plain_text (read only) boolean True if this notification can include a plain text rendering of an order directly within an email. Some desire this over an attachment
distribution_center_filters array of string If this notification supports it, this list of distribution center CODES will filter the notification to just those distribution centers.
include_affiliate boolean If true, and this notification supports it, affiliate information will be attached to all notifications of this type
include_order boolean If true, and this notification supports it, the order will be attached to all notifications of this type
include_order_plain_text boolean If true, and this notification supports it, a plain text order will be directly inserted into all notifications of this type
name (read only) string The name of this notification.
notification_group (read only) string A group for this notification. This name is only used for visual grouping within interfaces.
selected boolean True if this user wishes to receive this email notification.

Permission

Attributes
Name Data Type Description
permission_group (read only) string A group for this permission. This name is only used for visual grouping within interfaces.
permission_Name (read only) string The name of this permission.
selected boolean True if this user has this permission.

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.

SingleSignOnAuthorizeRequest

Attributes
Name Data Type Description
redirect_uri string The URL that the customer should be redirected to after they have approved a single sign on session.
state string An optional state variable that you provide. It will be returned to you on the redirect. You can inspect the state to validate the request is legitimate. We recommend using this field.

SingleSignOnAuthorizeResponse

Attributes
Name Data Type Description
expiration_dts string (dateTime) Expiration date/time after which the single sign-on login operation will have timed out
login_url string The URL that you should redirect the customer's browser to. This URL will begin the login process.

SingleSignOnTokenRequest

Attributes
Name Data Type Description
code string The code received on the redirect URI after the customer approved the single sign on request.
grant_type string Grant type. The value should be simple_key.

SingleSignOnTokenResponse

Attributes
Name Data Type Description
expiration_dts string (dateTime) Expiration date/time after which time the key is no longer valid
ip_address string IP address of the user which we recommend you lock the simple key's usage to.
simple_key string The simple key that can then be used to make SDK calls on the users behalf.

User

Attributes
Name Data Type Description
api_ip_address_masks array of string A list of IP addresses whitelisted for any user with API Access permission. Without this list, each ip address must be authenticated by a user, which can be a pain for some servers.
change_ftp_password_to string Supply a new FTP password using this field. Password are stored using one-way encryption, so they are never available anywhere in the system. The FTP password cannot be the same as the normal password.
change_password_to string Supply a new password using this field. Password are stored using one-way encryption, so they are never available anywhere in the system.
email string(150) Email address of user
full_name string Full name of user. This is used solely for human assistance and so the UltraCart staff knows who they are calling when there is a problem.
groups array of UserGroupMembership A list of groups for this merchant and whether or not this user is a member of those groups.
linked_accounts array of LinkedAccount A list of linked accounts and whether or not this user is mirrored to any of those accounts.
login string User name of user. Must be unique across a merchant account.
login_histories array of UserLogin A list of user logins over the past 90 days
notifications array of Notification A list of notifications the user receives.
otp_serial_number string OTP Serial Number such as Google Authenticator or Crypto Card.
permissions array of Permission A list of permissions the user enjoys for accessing the backend of UltraCart.
phone string Phone number of user. Please supply a valid phone number. When something breaks on your account, we need to be able to reach you.
user_id (read only) integer (int32) User id is a unique identifier for this user

UserGroupMembership

Attributes
Name Data Type Description
group_oid (read only) integer (int32) The unique object identifier (oid for short) for this group
member boolean True if this user is a member of the group.
name string The name of this group.

UserLogin

Attributes
Name Data Type Description
ip_address (read only) string IP Address
login (read only) string login
login_dts (read only) string (dateTime) Login date/time
user_agent (read only) string User Agent

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

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

401
Status Code 401: invalid credentials supplied

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

410
Status Code 410: Your authorized application has been disabled by UltraCart

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

429
Status Code 429: you have exceeded the allowed API call rate limit for your application.

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