This document outlines the purpose, technology, use cases, methods, objects and examples for using the Single Sign-On API.
This document focuses on the SOAP interface to this API.
The Single Sign-On API provides limited programmatic access to the customer database and allows for basic customer creation, retrieval, and interest group subscription and unsubscription.
This API also allows the login of a customer from a third-party site, providing a single-login experience between the system and the third-party site.
The Single Sign-On API exposes two primary native interfaces via .NET and SOAP.
Full documentation for this interface is available in the API Reference.
This section documents the SOAP interface to the API.
The SOAP API endpoint for any site is located at https://[siteurl]/global/api/singlesignon.asmx
This endpoint is enabled for access via SOAP as well as HTTP GET and POST. The Service Description is also available directly via this endpoint.
Note: For systems with satellite sites, the API will be available only under the primary site URL.
The Single Sign-On API uses the Permissions System to allow and deny access to certain users. Use of the API requires a user to be granted the various actions (under iSAMS / API / SingleSignOn) to be able to authenticate and perform the actions available under this API.
The Single Sign-On API supports password protection through a number of common hashing algorithms as well as plaintext passwords. In general, any customer passwords submitted to the Single Sign-On API should be in plaintext, and the API will hash the password if and as required. However, if your passwords are protected with an unsupported hash algorithm, you will need to submit passwords in their hashed forms. This API does not currently support encrypted passwords.
The following hashing algorithms are supported:
API methods that require a customer password currently include the Create and Login methods.
Note: A customer's password will never be returned in any response.
Error handling is primarily left to the caller. Any methods that return an ApiResponse object will provide additional details that can be used to assist when debugging problems.
Where a "Call Identifier" is returned in the Message field of the ApiResponse, then a full exception trace will be available from http://[siteurl]/logs/api/{Call Identifier}.txt
Available methods are listed below.
Available objects are listed below.
Customers API usage examples are available. These examples demonstrate the use of the API via a SOAP interface and are available in C# and Java.
See Authenticate.
Creates a new customer in the system with the supplied details.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| newCustomer | LoginCustomer | The details of the customer to create. |
Returns a CustomerLoginResponse object.
The provided LoginCustomer.ID field must be an empty String.
This method will fail if the customer's email already exists in the system, or if the email address is malformed or invalid.
If a password is not provided, a randomly-generated password will be created for the new customer. The password will not be returned in the CustomerLoginResponse.
In general, the provided password should be in plaintext. However, depending on your password policy, you may need to provide an already hashed password. See Password Requirements for more details.
Validates a customer's credentials against those stored in the system.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| String | The customer's email address. | |
| password | String | The customer's password. |
Returns a CustomerLoginResponse object, containing the customer's details if the login attempt was successful.
A successful login will return a CustomerLoginResponse with a true Success field and a populated ID field.
In general, the provided password should be in plaintext. However, depending on your password policy, you may need to provide an already hashed password. See Password Requirements for more details.
Retrieves a customer's data from the system.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerID | String | An encrypted customer ID. |
Returns a CustomerLoginResponse object containing the retrieved customer details.
Subscribes a customer to the specified interest group.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerID | String | The customer's encrypted customer ID. |
| interestGroup | String | The name of the interest group to subscribe to. |
Returns a CustomerLoginResponse object containing the customer's details.
The specified interest group will be created if it does not already exist.
Unsubscribes a customer from the specified interest group.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| customerID | String | The customer's encrypted customer ID. |
| interestGroup | String | The name of the interest group to unsubscribe from. |
Returns a CustomerLoginResponse object containing the customer's details.
Contains basic information about the result of a method call, along with a LoginCustomer containing customer data.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Customer | LoginCustomer | A LoginCustomer containing the customer's details. | This field will be null on failure. |
Contains limited data on a customer.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | String | Encrypted customer ID of the customer. | |
| String | Email of the customer. | ||
| FirstName | String | First name of the customer. | |
| LastName | String | Last name of the customer. | |
| Password | String | Password of the customer. | This will never be returned from the system, and is only required when creating a customer. |
| InterestGroups | String[] | Array of interest groups currently subscribed to by the customer. |
Used to indicate the result of an API method call.
In addition to standard API response codes, the following response codes may be returned from the Single Sign-On API:
| Code | Description |
|---|---|
| 7990 | The supplied customer login details are incorrect. |
| 7991 | The supplied customer ID is invalid. |
| 7992 | The supplied customer details are invalid. |
| 7993 | The customer already exists. |