getSingleSignOnToken

This server-only method returns a single sign-on "token" that can be used in client-side requests to automatically log a user into the system. This is to be used in the case where a web site external to Convio has authenticated the site visitor and wants to direct the user's browser to the Convio system and have them automatically logged in to the Convio system. The external web server, after verifying the identity of the visitor, calls this API method to get a token that will log the user into the Convio system when sent by the visitor's browser in a subsequent HTTP request. This token is only valid for the specific user and only for a limited time (typically, a few minutes).

To log in to the Convio system and visit most pages, the token need only be presented one time to initiate the logged-in session. However, if other API methods are used during the visit, this token should be included in all API requests to verify that the API methods are being called from a trusted source. While the token cannot be used after its time limit to log a user in, it can be used for the duration of the current session to verify the trustworthiness of the source.

The token can be used in the following ways to log the visitor in to the Convio system:

Call the singleSignOn API method
Add the token to any Convio system URL as the value of the "sso_auth_token" URL parameter

Please review the authentication and security guidance before using this or any other API method available in the site configuration..

Post URL

Deconstructing the URL
* In most cases secure2.convio.net matches a client's secure domain. However, in some cases this will be different. If your organization uses Convio for fundraising, the correct secure domain for the API is identical to the secure domain for your fundraising forms. So if the sample above does not work, look for the unique secure domain used for your organization and replace the secure2.convio.net portion above with this URL.

*Here, organization is a client's unique identifier in the Convio system. Every client has a unique value that represents their instance of the product. If you're organization uses a custom secure URL for donations, the organization portion of the URL may not be necessary, contact support for assistance.

Example: https://demo-secure.convio.net/demo829/site/SRConsAPI. Here you'll notice that demo-secure.convio.net is used for the domain, and demo829 is used for the organization.

Authentication

Authenticating Convio Server API calls is a three-stage process. First, the IP address of the server invoking the API call will be checked against the list of allowed IP ranges, per the Convio Site Configuration parameters. If the API is being invoked from a server in the allowed IP range, then the login_name and login_password parameters will be used to log in to the Convio site. Finally, once the login credentials have been verified, the account specified by the login credentials will be examined to ensure that it has the Contact Management “Use Convio API” permission. If all the above hold, the caller will be authenticated and the API call will proceed. If any of the above fail, then the call will not be authenticated and an error message will be returned.

Parameters

The following parameters apply:

Name	Description
api_key	Required. An arbitrary value that must be passed when invoking the Convio Client and Server APIs. The value passed by the caller must match the value in the CONVIO_API_KEY site configuration parameter, which is unique for each Convio site.
v	Required. API version to invoke. Must be "1.0".
method	Required. Specifies which method to perform. To invoke this method use the value "getSingleSignOnToken"
response_format	Optional. Specifies the format in which to return the response. Can be either "xml" (the default value) or "json".
login_name	Required. Specifies the user name of the account to authenticate.
login_password	Required. Specifies the password of the account to authenticate.
cons_id	Required*. The internal constituent ID of the user.
member_id	Required*. The external member ID of the user.

*Either cons_id or member_id must be specified order to locate the record of the user to log in.

If cons_id is given, then it is the only thing used to search.
If cons_id is absent and member_id is given, then it is the only thing used to search.
- If one record matches member_id, a token for it is returned.
- If multiple records match member_id, then this is an error and no token is returned.

Response

Success

A successful invocation sends either a URL redirect (if the redirect parameter was specified) or an identifier for the new record is returned. The HTTP status code is 200. The response is formatted as XML by default, but the response_format input parameter can be used to specify either XML or JSON formatting. For example:

XML format:

<getSingleSignOnTokenResponse
  xmlns="http://convio.com/crm/v1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://convio.com/crm/v1.0
  http://service.convio.net/xmlschema/crm.public.v1.xsd">
  <token>5F8p37tMzmB9qfjoXd9i2nkb_INrxXfa8wL
  7rbpSQkm5gwEgRQV5F6YmJwfKbIIgbHbeqaJcGNLWGdJqrxegrw..</token>
  <cons_id>1001641</cons_id>
</getSingleSignOnTokenResponse>

JSON format:

{"getSingleSignOnTokenResponse": 
  {"cons_id":"1001641",
   "token":"5F8p37tMzmB9qfjoXd9i2nkb_INrxXfa8wL7rbpSQkm5gw
            EgRQV5F6YmJwfKbIIgbHbeqaJcGNLWGdJqrxegrw.."  
  }
}

Error

If there is an error, this returns either a URL redirection request (if the redirect parameter was specified) or the error code and message. The HTTP status code is 403. For example:

XML format:

<errorResponse
  xmlns="http://convio.com/crm/v1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://convio.com/crm/v1.0
  http://service.convio.net/xmlschema/crm.public.v1.xsd">
  <code>14</code>
  <message>The specified record does not exist.</message>
</errorResponse>

JSON format:

{"errorResponse":{"code":"14","message":
 "The specified record does not exist."}}

See the complete list of HTTP Status codes and Error codes for calling from another application.

Client Community
Log in to chat with other clients and partners using APIs and share code snippets.