Guest and Invitation End Points (Version 1)

Written by Cirrus Product Documentation | Apr 4, 2022 7:24:12 PM

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

uri	/guest/invite
http operation	POST
success response	201
error response	400 The invitation could not be created due to error in the supplied data 403 authentication/authorization error 404 A supplied SP entity id was not found; or a supplied sponsor was not found and could not be created

Required Parameters

Name	Description	Format
spEntityId	Entity id of the SP for which you want to invite a guest	An entity id.
serviceName	Short name of the SP	Alphanumeric.
emailAddress	Email address of the guest	rfc2822.
emailSubject	Subject line of the email invitation	Alphanumeric; 1-256 chars.
A Sponsor	Either: A sponsorMail address matching one authorized to send invitations; the sponsorMail can be for a service account sponsorMail, sponsorEppn, and sponsorSurname to create a new sponsor if needed	sponsorMail - (RFC 4524) sponsorEppn - (Formal Definition) sponsorSurname - Alphanumeric; 1-256 chars.

Optional Parameters

Name	Description	Format
clientRequestID	A client supplied unique identifier for the request. If supplied, will be returned in response.	Alphanumeric; 1-256 chars.
emailText	Text of the email invite. (See email template options)	Alphanumeric; Can be null. Max 4000 chars.
sponsorGivenname	Given name of the sponsor.	Alphanumeric; 1-256 chars.
expirationDate	Date the guest login will expire. Default 1 year.	ISO8601 date. Must be at least 24 hours.
validityPeriod	Number of days the invitation will be valid. Default 3 days.	Numeric. Must be > 0.
applicationName	Name of the application, which will appear in the email invite, and on claim page.	Alphanumeric; Can be null. Max 256 chars
applicationLink	Link to the application. (See email template options)	URL.
sendEmail	A flag to control the sending of the invitation email -- used in connection with self-assertion claiming.	Boolean (true or false), Default - true
customData	A set of key/value pairs that will be saved with the guest, and asserted back during login.	JSON object.

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
}

Sample Response

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

uri	/guest/id
http operation	GET
success response	200
error response	403 authentication/authorization error. 404 The guest with the supplied id was not found.

Required Parameters

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

Name	Description	Format
id	Id of the guest.	An id as returned in the body of a guest/invite response.

Sample Request

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

Sample Response (before invitation is accepted)

HTTP 200 OK

{
"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.

uri	/batchInviteCsv
http operation	POST
content-type	multipart/form
success response	201
error response	400 The invitation could not be created due to error in the supplied data 403 authentication/authorization error 404 A supplied SP entity id was not found; or a supplied sponsor was not found and could not be created

Required Form Elements

Name	Description	Format
spEntityId	Entity id of the SP for which you want to invite a guest	An entity id.
sponsorEppn	eduPersonPrincipalName of the default sponsor for the batch.	(Formal Definition)
sponsorMail	Email address of the sponsor. (optional if sponsorEppn exists)	(RFC 4524)
sponsorSurname	Surname of the sponsor. (optional if sponsorEppn exists)	Alphanumeric; 1-256 chars.
clientRequestID	A client supplied unique identifier for the invitation.	Alphanumeric; 1-256 chars.
cfile	csv file. Each row in the file is one invitation.	Plain text file; comma separated values enclosed in double-quotes; headers matching the names of the invitation parameters below.

Optional Form Elements

Name	Description	Format
emailText	Text of the email invite. (See email template options)	Alphanumeric; Can be null. Max 4000 chars.
emailSubject	Subject line of the email invitation	Alphanumeric; 1-256 chars.
sponsorGivenname	Given name of the sponsor	Alphanumeric; 1-256 chars.
expirationDate	Date the guest login will expire. Default 1 year.	ISO8601 date. Must be at least 24 hours.
validityPeriod	Number of days the invitation will be valid. Default 3 days.	Numeric. Must be > 0.
applicationName	Name of the application, which will appear in the email invite, and on claim page.	Alphanumeric; Can be null. Max 256 chars.
applicationLink	Link to the application. (See email template options)	URL.

Required Invitation Parameters

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

Name	Description	Format
emailAddress	Email address of the guest	rfc2822.

Optional Invitation Parameters

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

Name	Description	Format
customData	You can provide your own custom key:value pairs with this parameter.	A string containing key:value pairs, separated by commas. e.g. "bannerId:12345678,other_key:other_value"
sponsorEppn	You can provide a per-invite sponsor which overrides the default sponsor.	eppn
applicationName	Name of the application, which will appear in the email invite, and on the claim page. Overrides the applicationName value from the batch form, and the service provider.	Alphanumeric; Can be null. Max 256 chars.
applicationLink	Link to the application. (See email template options) Overrides the applicationLink value from the batch form.	URL.

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

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.

uri	/batchStatus/batchId
http operation	GET
success response	200
error response	403 authentication/authorization error 404 No invitation batch matched the supplied id.

Required Parameters

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

Name	Description	Format
batchId	Id of the batch.	A batchId as returned in the body of a batchInvite or batchInviteCsv response.

Sample Request

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

Sample Response

Headers

HTTP 200 OK

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

uri	/guest/id
http operation	DELETE
success response	204
error response	403 authentication/authorization error. 404 The guest with the supplied id was not found.

Required Parameters

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

Name	Description	Format
id	Id of the guest.	An id as returned in the body of a guest/invite response.

Sample Request

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

Sample Response

HTTP 204 No Content

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"
]
}

View full post