Guest and Invitation End Points (Version 1)

Overview

Use this API documentation for:

• Linking an internal enterprise identifier to an external identity (when you have an internal record for a user but don't want to create and manage the username and password)
• Allowing an internal user to "sponsor" an external user logging in with an external identity (like a student sponsoring a parent's access via social login, or a faculty member inviting a research collaborator)

Base URI

The base uri for the api:  

https://apps.cirrusidentity.com/console/api/v1

Authorization

The API uses standard http Basic Auth. Cirrus will supply you with a username/password pair. If the authentication/authorization fails, an http 403 response code is returned.

Requests

Data supplied in the body of a request (ie. in a POST request) must be in the form of a json document, and you should set the Content-Type header to application/json.

Responses

The response body will always be a json document, containing either the result of the operation if successful, or an errors object. (See examples)

If an operation is successful the http response code will be an appropriate 2xx code.

 If the operation fails for some reason, an appropriate http 4xx or 5xx response code will be returned, and the error(s) will be provided in the response body.

APIs

Guest Invite

Required Parameters

Optional Parameters

Sample Request

The following is a valid request which contains all required, and some optional, parameters.

{
   "spEntityId": "http://apps-dev2.cirrusidentity.com/shibboleth",
   "clientRequestId": "x0021",
   "serviceName": "Cloud Research Wiki",
   "emailAddress": "some.person@gmail.com",
   "emailSubject": "Invitation to join Cloud research",
   "emailText": "This is a sample body for the email.",
   "sponsorEppn": "irene@cirrusidentity.com",
   "expirationDate": "2030-08-01T07:00:00Z",
   "validityPeriod": 5
}

Here is the response that would be returned from the previous request. The response code is 201 to indicate that a new guest object has been created. The Location header will have a uri to the new guest object.

HTTP 201 Created

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=***REDACTED***
Location: https://apps.cirrusidentity.com/console/api/v1/guest/c9854ba210264d3db40e1a166fe88076

The body of the response contains a json document with keys ‘spEntityId’, ‘guest’, and ‘clientRequestId’ (if it was specified in the request). The ‘guest’ key returns a json map of the new guest object.

{
   "spEntityId": "http://apps-dev2.cirrusidentity.com/shibboleth",
   "guest": {
     "mail": null,
     "uid": "c9854ba210264d3db40e1a166fe88076",
     "domain": "cirrusidentity.com",
     "status": "invited",
     "validityPeriod": 5,
     "expirationDate": "2016-09-04T07:40:17Z",
     "invitationAcceptedDate": null,
     "sn": "",
     "givenName": "",
     "createDate": "2015-09-04T07:40:17Z",
     "mailForInvite": "some.person@gmail.com",
     "modifyDate": "2015-09-04T07:40:17Z",
     "eppn": "",
     "spEntityID": "http://apps-dev2.cirrusidentity.com/shibboleth",
     "spName": "apps-dev2"
     "customData": {
        "universityId": "992012345"
     }
   },
   "clientRequestId": "x0021"
}

Sample Error Response

Here is the response that would be returned from a request that was missing the spEntityId parameter.

HTTP 400 Bad Request

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Connection: close
Server: Apache-Coyote/1.1
Set-Cookie: ***REDACTED***

{
   "errors": [
     {
      "object": "com.socialidp.spadmin.api.GuestInviteCommand",
      "message": "Property [spEntityId] of class [class
      com.socialidp.spadmin.api.GuestInviteCommand] cannot be null",
      "rejected-value": null,
      "field": "spEntityId"
     }
   ]
}

Guest Read

Required Parameters

The only parameter is the guest id which is specified in the uri.

Sample Request

GET https://apps.cirrusidentity.com/console/api/v1/guest/c9854ba210264d3db40e1a166fe88076

Sample Response (before invitation is accepted)

HTTP 200 OK

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=***REDACTED***
Location: https://apps.cirrusidentity.com/console/api/v1/guest/c9854ba210264d3db40e1a166fe88076

{
     "mail": null,
     "uid": "c9854ba210264d3db40e1a166fe88076",
     "domain": "cirrusidentity.com",
     "status": "invited",
     "validityPeriod": 5,
     "expirationDate": "2016-09-04T07:40:17Z",
     "invitationAcceptedDate": null,
     "sn": "",
     "givenName": "",
     "createDate": "2015-09-04T07:40:17Z",
     "mailForInvite": "some.person@gmail.com",
     "modifyDate": "2015-09-04T07:40:17Z",
     "eppn": "",
     "spEntityID": "http://apps-dev2.cirrusidentity.com/shibboleth",
     "spName": "apps-dev2"
     "customData": {
          "universityId": "992012345"
     }
}

Sample Response (after invitation is accepted)

Note that after the person has accepted the invite and it has been validated, the status will be "valid", and the surname, given name, mail, invitationAccepted, and eppn fields will be filled in. The mail field may be different from the email address used in the invitation, as the guest can choose to assert a different email address.

HTTP 200 OK

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
Set-Cookie: ***REDACTED***
Location: https://apps.cirrusidentity.com/console/api/v1/guest/c9854ba210264d3db40e1a166fe88076

{
     "mail": "joe.doe@gmail.com",
     "uid": "c9854ba210264d3db40e1a166fe88076",
     "domain": "cirrusidentity.com",
     "status": "valid",
     "expirationDate": "2016-09-04T07:40:17Z",
     "invitationAcceptedDate": "2015-09-04T07:40:17Z",
     "sn": "Doe",
     "givenName": "Joe",
     "createDate": "2015-09-04T07:40:17Z",
     "mailForInvite": "some.person@gmail.com",
     "modifyDate": "2015-09-04T07:40:17Z",
     "validityPeriod": 3,
     "eppn": "alsdlkasdlgko@gmail.com",
     "spEntityID": "http://apps-dev2.cirrusidentity.com/shibboleth",
     "spName": "apps-dev2"
     "customData": {
          "universityId": "992012345"
     }
}

Sample Error Response

Here is the response that would be returned from a request that had an invalid id.

HTTP 404 Not Found

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Connection: close
Server: Apache-Coyote/1.1
Set-Cookie: ***REDACTED***

{
   "errors": [
     "No person with id: 123456789"
   ]
}

Guest Batch Invite

You can provide a batch of invites by submitting an http POST with a content-type of "multipart/form" and a csv file as one of the form elements. The required form elements and csv format are described below. See the example below which shows how to do this using the "curl" command.

Required Form Elements

Optional Form Elements

Required Invitation Parameters

Each row of the csv file must have the following required parameters.

Optional Invitation Parameters

Each row of the csv file may have the following optional parameters.

Sample Request

The following is a valid request which contains all required, and some optional, parameters.

Sample Response

Here is the response that would be returned from the previous request. The response code is 201 to indicate that a new invitation batch has been created. The Location header will have a uri to the status object of the batch. (See batchStatus endpoint.)

The body of the response contains a json document with a key:  ‘batchId’ which is required to query the processing status of the batch.

Headers

HTTP 201 Created

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=***REDACTED***
Location: https://apps.cirrusidentity.com/console/api/v1/batchStatus/c9854ba210264d3db40e1a166fe88076

Body

{
   "clientRequestID":"1",
   "spEntityId":"http://sp.myorg.edu",
   "batchId": "c9854ba210264d3db40e1a166fe88076",
   "errors": []
}

Sample Error Response

Here is the response that would be returned from a request that was missing the spEntityId parameter.

HTTP 400 Bad Request

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Connection: close
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=***REDACTED***

{
"errors": ["Required parameter was not supplied: spEntityId."]
}

Example curl command and csv file

The following is a curl command which submits a file (test.csv). For readability, '\' characters are used to split the command onto multiple lines. This generates a standard multi-part form submit. Each "-F" element is a form element.

curl command

curl -L -v -u 'apikey:apisecret' \
-F cfile=@test.csv \
-F spEntityId=http://sp.myorg.edu/ \
-F sponsorEppn=admin@myorg.edu \
-F clientRequestID=a1 \
https://apps.cirrusidentity.com/console/api/v1/batchInviteCsv

• The "-v" is optional, but it useful for debugging.
• If the sponsor hasn't already been created in the service provider, then you should also include:       
• -F sponsorGivenname=John \
• -F sponsorSurname=Doe \
• -F sponsorEmail=someemail@myorg.edu
• clientRequestID is required, but it can be any string. It is returned in results, to allow the client to track requests.

Here is an example of a minimal csv file supplied to the curl command above.

Sample csv file

"emailAddress","customData"
"cindy.cirrus@gmail.com","bannerid:11111111"
"steve.stratus@gmail.com","bannerid:12345678"

Batch Invite Status

Get the status of a batch invite process. This will return the total number of invitations in the batch, the number currently processed, and a list of errors encountered.

Required Parameters

The only parameter is the batch id which is specified in the uri.

Sample Request

GET https://apps.cirrusidentity.com/console/api/v1/batchStatus/c9854ba210264d3db40e1a166fe88076

Sample Response

Headers

HTTP 200 OK

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=***REDACTED***
Location: https://apps.cirrusidentity.com/console/api/v1/batchStatus/c9854ba210264d3db40e1a166fe88076

Body

{
   "batchId": "c9854ba210264d3db40e1a166fe88076",
   "batchSize": 1000,
   "numberProcessed": 20,
   "errors": [
     {
        "clientRequestId": "x0099",
        "emailAddress": "foo@",
        "message": "Invalid email address"
     }
   ]
}

Sample Error Response

Here is the response that would be returned from a request that had an invalid batch id.

HTTP 404 Not Found

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Connection: close
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=***REDACTED***

{
   "errors": [
     "No batch with id: 123456789"
   ]
}

Guest Delete

Required Parameters

The only parameter is the guest id which is specified in the uri.

Sample Request

DELETE https://apps.cirrusidentity.com/console/api/v1/guest/c9854ba210264d3db40e1a166fe88076

{
   "mail": "joe.doe@gmail.com",
   "uid": "c9854ba210264d3db40e1a166fe88076",
   "domain": "cirrusidentity.com",
   "status": "valid",
   "expirationDate": "2016-09-04T07:40:17Z",
   "invitationAcceptedDate": "2015-09-04T07:40:17Z",
   "sn": "Doe",
   "givenName": "Joe",
   "createDate": "2015-09-04T07:40:17Z",
   "mailForInvite": "some.person@gmail.com",
   "modifyDate": "2015-09-04T07:40:17Z",
"validityPeriod": 3,
"eppn": "alsdlkasdlgko@gmail.com",
"spEntityID": "http://apps-dev2.cirrusidentity.com/shibboleth",
"spName": "apps-dev2"
}

Sample Response

HTTP 204 No Content

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=***REDACTED***
Location: https://apps.cirrusidentity.com/console/api/v1/guest/c9854ba210264d3db40e1a166fe88076

Sample Error Response

Here is the response that would be returned from a request that had an invalid id.

HTTP 404 Not Found

Date: Fri, 04 Sep 2015 07:40:18 GMT
Transfer-Encoding: Identity
Content-Type: application/json;charset=UTF-8
Connection: close
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=***REDACTED***

{
   "errors": [
     "No person with id: 123456789"
   ]
}