Documentation

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

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

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.

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

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.

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

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

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

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

© Copyright Cirrus Identity, Inc.