Guest and Sponsor Endpoints

Written by Cirrus Product Documentation | Jul 6, 2022 7:00:00 PM

LIST Guests

uri	/guests/{domain}
description	Paginated listing of all guests for an organization's domain.
http operation	GET
success response	200
error response	403 authentication/authorization error associated with the requested domain

Required Parameters

Name	Description	Format
domain	Organization domain that owns the guests.	rfc1035

Optional Parameters

Name	Description	Format
offset	The number of records to offset the page in the response.	Numeric; Must be >= 0.
limit	The number of records per page returned in the response. If a limit is not provided, a default limit of 500 per page will be returned.	Numeric; Must be >= 0.
searchArg	An optional search parameter that allows searching over both the mail attribute and the surname attribute for the guest objects.	String
linkGroup	An optional search parameter that allows searching by the assigned link group identifier. A valid linkGroupId provide by the /linkGroups API	Numeric; Must be >= 0
status	An optional search parameter that allows searching by the current guest status. Allowable status values are: invited: The guest is in the process of claiming an invitation, but has not completed the process valid: The guest has completed the claim process and is allowed to access the service provider valid-bypass: The guest has bypassed the Cirrus Invitation Service during the claiming process and is using a login method that is not managed by Cirrus Identity expired: The guest is past the expiration date for their invitation, or has been revoked	String
type	An optional search parameter to return guests based on one of the associated time stamps specified by the value assigned to type. When used, requires the use of at least the "start" or "end" parameter. The available types are: CREATED: the date-time when the guest object was created MODIFIED: the date-time when the guest object was last modified EXPIRATION: the date-time when the guest object is set to expire	String
start	The start date-time of a window (in UTC) to return guest objects. If not provided, defaults to the current date-time.	String; formatted in 'yyyy-mm-ddThh24:mi:ss'
end	The end date-time of a window (in UTC) to return guest objects. If not provided, defaults to the current date-time.	String; formatted in 'yyyy-mm-ddThh24:mi:ss' and in UTC

Sample Request

The following is a valid request which contains pagination parameters.

curl -i -u {api_key}:{api_secret} \
-d offset=10 \
-d limit=5 \
https://apps.cirrusidentity.com/console/api/v2/guests/{domain}

Sample Response

Here is the response that would be returned from the sample request. Note: For brevity, some of the guest records have been replaced by ellipsis.

HTTP/1.1 200

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Fri, 05 Jan 2018 00:26:35 GMT
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 3334
Connection: keep-alive

{

    "href": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net?offset=10&amp;amp;amp;limit=5",
    "totalCount": 59,
    "offset": 10,
    "limit": 5,
    "count": 5,
    "first": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net?limit=5",
    "next": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net?offset=15&amp;amp;amp;limit=5",
    "prev": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net?offset=5&amp;amp;amp;limit=5",
    "guests": [
        {
            "href": "https://apps.cirrusidentity.com/console/api/v2/guest/06e901d0-9d2d-418d-b757-3263aa3190e7",
            "givenName": "PENDING_GUEST_FIRST_NAME",
            "sn": "PENDING_GUEST_LAST_NAME",
            "uid": "06e901d0-9d2d-418d-b757-3263aa3190e7",
            "mail": null,
            "domain": "athena-institute.net",
            "status": "invited",
            "expirationDate": "2018-11-28T23:53:00Z",
            "createDate": "2017-11-29T00:50:55Z",
            "modifyDate": "2017-11-29T00:50:55Z",
            "eduPersonPrincipalName": null,
            "customData": {},
            "socialProvider": "",
            "invitations": {
                "href": "https://apps.cirrusidentity.com/console/api/v2/guest/06e901d0-9d2d-418d-b757-3263aa3190e7/invitations"
            }
        },
        {
            "href": "https://apps.cirrusidentity.com/console/api/v2/guest/82d84ccd-fa8f-407d-a01d-8739ed00d66d",
            "givenName": "Cindy",
            "sn": "Cirrus",
            "uid": "82d84ccd-fa8f-407d-a01d-8739ed00d66d",
            "mail": "cindy.cirrus@gmail.com",
            "domain": "athena-institute.net",
            "status": "valid",
            "expirationDate": "2018-12-13T00:03:55Z",
            "createDate": "2017-12-13T00:05:58Z",
            "modifyDate": "2018-01-03T23:19:22Z",
            "eduPersonPrincipalName": "123456789123456789123@google.com",
            "customData": {
                "cirrusId": "d9dd1d0f-73db-4e57-912f-ebd92037704a",
                "orgUid": "88776655"
            },
            "socialProvider": "",
            "invitations": {
                "href": "https://apps.cirrusidentity.com/console/api/v2/guest/82d84ccd-fa8f-407d-a01d-8739ed00d66d/invitations"
            }
        },
    ...
    ]
}

Sample Request with Search

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

curl -i -u {api_key}:{api_secret} \

https://apps.cirrusidentity.com/console/api/v2/guests/{domain}?offset=0&limit=3&searchArg=connie.contrail@gmail.com

Sample Response

Here is the response that would be returned from the sample request. Note: For brevity, some of the guest records have been replaced by ellipsis.

HTTP/1.1 200

Date: Wed, 19 Sep 2018 23:15:39 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: **REDACTED**
Set-Cookie: **REDACTED**

{
  "href": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net?limit=3",
  "totalCount": 4,
  "offset": 0,
  "limit": 3,
  "count": 3,
  "first": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net?limit=3",
  "next": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net?offset=3&limit=3",
  "prev": null,
  "guests": [
    {
      "href": "https://apps.cirrusidentity.com/console/api/v2/guest/215d784b-248a-4b79-80a9-626e888f4504",
      "givenName": "Connie",
      "sn": "Contrail",
      "uid": "215d784b-248a-4b79-80a9-626e888f4504",
      "mail": "connie.contrail@gmail.com",
      "domain": "athena-institute.net",
      "status": "valid",
      "expirationDate": "2019-09-17T21:58:32Z",
      "createDate": "2018-09-17T21:59:07Z",
      "modifyDate": "2018-09-17T21:59:21Z",
      "eduPersonPrincipalName": "100546218585243689914@google.com",
      "customData": {},
      "socialProvider": "google",
      "invitations": {
        "href": "https://apps.cirrusidentity.com/console/api/v2/guest/215d784b-248a-4b79-80a9-626e888f4504/invitations"
      }
    }...

Here is the response that would be returned from a request where the domain was not authorized by the API key. This error is returned rather than a HTTP-404 error if the incorrect domain is provided because the API key authorization fails.

HTTP/1.1 403

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Fri, 05 Jan 2018 04:09:46 GMT
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 111
Connection: keep-alive

{"errors":["{api_key} does not have domain authorization for domain: {domain}"]}

LIST Guests by CustomAttribute

uri	/guests/{domain}/byCustomAttribute
description	Get guests that have a specific customeData attribute name and value pair.
http operation	GET
success response	200
error response	403 authentication/authorization error associated with the requested domain

Required Parameters

Name	Description	Format
domain	Organization domain that owns the guests.	rfc1035
attributeName	The guest customeData attribute name to look for.	String
attributeValue	The value for the customData attribute to look for.	String

Optional Parameters

Name	Description	Format
None

Sample Request

The following is a valid request which contains all required parameters.

curl -i -u {api_key}:{api_secret} \
-d attributeName='testId' \
-d attributeValue='A1234' \
https://apps.cirrusidentity.com/console/api/v2/guests/{domain}/byCustomAttribute

Sample Response

Here is the response that would be returned from the sample request.

HTTP/1.1 200 
Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Fri, 05 Jan 2018 18:29:42 GMT
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 763
Connection: keep-alive

{
    "href": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net/byCustomAttribute?attributeName=testId&amp;attributeValue=A1234",
    "totalCount": 1,
    "count": 1,
    "guests": [
        {
            "href": "https://apps.cirrusidentity.com/console/api/v2/guest/5d50e7d288554a5c98bdfad13cd69988",
            "givenName": "Cindy",
            "sn": "Cirrus",
            "uid": "5d50e7d288554a5c98bdfad13cd69988",
            "mail": "cindy.cirrus@gmail.com",
            "domain": "athena-institute.net",
            "status": "valid",
            "expirationDate": "2018-03-12T23:59:59Z",
            "createDate": "2017-04-19T21:39:42Z",
            "modifyDate": "2018-01-05T18:00:23Z",
            "eduPersonPrincipalName": "cindy.cirrus@gmail.com",
            "customData": {
                "testId": "A1234"
            },
            "socialProvider": "",
            "invitations": {
                "href": "https://apps.cirrusidentity.com/console/api/v2/guest/5d50e7d288554a5c98bdfad13cd69988/invitations"
            }
        }
    ]
}

Here is the response that would be returned from a request where the attribute name is not found.

HTTP/1.1 200

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Fri, 05 Jan 2018 18:58:19 GMT
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 192
Connection: keep-alive

{"href":"https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net/byCustomAttribute?attributeName=testId-dummy&amp;attributeValue=A1234","totalCount":0,"count":0,"guests":[]}

Here is the response that would be returned from a request where the attribute value is not found.

HTTP/1.1 200

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Fri, 05 Jan 2018 19:00:05 GMT
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 192
Connection: keep-alive

{"href":"https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net/byCustomAttribute?attributeName=testId&amp;attributeValue=A1234-dummy","totalCount":0,"count":0,"guests":[]}

HTTP/1.1 403

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Fri, 05 Jan 2018 04:09:46 GMT
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 111
Connection: keep-alive

{"errors":["{api_key} does not have domain authorization for domain: {domain}"]}

GET Guest

uri	/guest/{uid}
description	Return the attributes for a guest.
http operation	GET
success response	200
error response	403 authentication/authorization error 404 UID not found

Required Parameters

Name	Description	Format
UID	The uid assigned to the guest record.	string

Optional Parameters

Name	Description	Format
None

Sample Request

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

curl -i -u {api_key}:{api_secret} \
https://apps.cirrusidentity.com/console/api/v2/guest/{uid}

Sample Response

Here is the response that would be returned from the sample request.

HTTP/1.1 200 
Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Wed, 17 Jan 2018 20:56:00 GMT
Set-Cookie: JSESSIONID=***REDACT***
Set-Cookie: AWSELB=***REDACT***
Content-Length: 615
Connection: keep-alive

{
  "href": "https://apps.cirrusidentity.com/console/api/v2/guest/2666957e-b1de-4e16-a301-a32bacfaa091",
  "givenName": "Connie",
  "sn": "Contrail",
  "uid": "2666957e-b1de-4e16-a301-a32bacfaa091",
  "mail": "connie.contrail@gmail.com",
  "domain": "athena-institute.net",
  "status": "valid",
  "expirationDate": "2019-01-17T20:44:02Z",
  "createDate": "2018-01-17T20:44:20Z",
  "modifyDate": "2018-01-17T20:45:51Z",
  "eduPersonPrincipalName": "11223344556677889@facebook.com",
  "customData": {},
  "socialProvider": "facebook",
  "invitations": {
    "href": "https://apps.cirrusidentity.com/console/api/v2/guest/2666957e-b1de-4e16-a301-a32bacfaa091/invitations"
  }
}

Here is the response that would be returned from a request where the UID is not found.

HTTP/1.1 404 
Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Wed, 17 Jan 2018 21:10:27 GMT
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 83
Connection: keep-alive

{
  "errors": [
    "Guest not found for uid: 2666957e-b1de-4e16-a301-a32bacfaa091-dummy."
  ]
}

GET Guest invitations

uri	/guest/{uid}/invitations
description	Return the invitations currently held by a guest.
http operation	GET
success response	200
error response	403 authentication/authorization error 404 UID not found

Required Parameters

Name	Description	Format
UID	The uid assigned to the guest record.	string

Optional Parameters

Name	Description	Format
None

Sample Request

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

curl -i -u {api_key}:{api_secret} \

https://apps.cirrusidentity.com/console/api/v2/guest/{uid}/invitations

Sample Response

Here is the response that would be returned from the sample request.

HTTP/1.1 200

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Wed, 17 Jan 2018 21:16:04 GMT
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 956
Connection: keep-alive

{
  "href": "https://apps.cirrusidentity.com/console/api/v2/guest/2666957e-b1de-4e16-a301-a32bacfaa091/invitations",
  "totalCount": 1,
  "invitations": [
    {
      "href": "https://apps.cirrusidentity.com/console/api/v2/invitation/ac80d916-7918-4887-a9df-d158416a5601",
      "uid": "ac80d916-7918-4887-a9df-d158416a5601",
      "createDate": "2018-01-17T20:44:02Z",
      "modifyDate": "2018-01-17T20:45:51Z",
      "mailForInvite": "connie.contrail@gmail.com",
      "status": "claimed",
      "invitationDate": "2018-01-17T20:44:02Z",
      "invitationAcceptedDate": "2018-01-17T20:45:51Z",
      "expirationDate": "2019-01-17T20:44:02Z",
      "validityPeriod": 3,
      "givenName": "",
      "sn": "",
      "customData": {
        "course": "Course1",
        "section": "Section1"
      },
      "spEntityID": "https://research.athena-institute.net/shibboleth",
      "sponsor": {
        "href": "https://apps.cirrusidentity.com/console/api/v2/sponsor/11aa22bb33cc44dd55ee66ff77aa88bb"
      },
      "guest": {
        "href": "https://apps.cirrusidentity.com/console/api/v2/guest/2666957e-b1de-4e16-a301-a32bacfaa091"
      }
    }
  ]
}

Here is the response that would be returned from a request where the UID is not found.

HTTP/1.1 404

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Wed, 17 Jan 2018 21:10:27 GMT
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 83
Connection: keep-alive

{
  "errors": [
    "Guest not found for uid: 2666957e-b1de-4e16-a301-a32bacfaa091-dummy."
  ]
}

UPDATE Guest customData

uri	/guest/{uid}/customData
description	Update the customeData name-value pairs for a guest.
http operation	PUT
success response	200
error response	403 authentication/authorization error associated with the requested domain 404 uid not found or used HTTP-POST instead of HTTP-PUT

Required Parameters

Name	Description	Format
uid	The uid assigned to the guest record.	String
new customData	The body of the PUT should be a JSON document with a content-type of "application/json" containing the new customData name-value pairs. For example the document may look like the following: {"customData": { "foo" : "bar", "fu" : "baz"}}	JSON Document

Optional Parameters

Name	Description	Format
None

Sample Request

The following is a valid request which contains all required parameters. In this request, we are adding the "sampleId" to the customData and retaining the existing "testId" entry.

curl -i -u {api_key}:{api_secret} \
-X PUT \
-H 'Content-Type: application/json' \
-d '{ "customData": {"testId": "A1234", "sampleId": "S-9876"}}' \
https://apps.cirrusidentity.com/console/api/v2/guest/2666957e-b1de-4e16-a301-a32bacfaa091/customData

Sample Response

Here is the response that would be returned from the previous request.

HTTP/1.1 200

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Wed, 17 Jan 2018 21:25:45 GMT
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 651
Connection: keep-alive

{

  "href": "https://apps.cirrusidentity.com/console/api/v2/guest/2666957e-b1de-4e16-a301-a32bacfaa091",
  "givenName": "Connie",
  "sn": "Contrail",
  "uid": "2666957e-b1de-4e16-a301-a32bacfaa091",
  "mail": "connie.contrail@gmail.com",
  "domain": "athena-institute.net",
  "status": "valid",
  "expirationDate": "2019-01-17T20:44:02Z",
  "createDate": "2018-01-17T20:44:20Z",
  "modifyDate": "2018-01-17T21:25:45Z",
  "eduPersonPrincipalName": "11223344556677889@facebook.com",
  "customData": {
    "testId": "A1234",
    "sampleId": "S-9876"
  },
  "socialProvider": "facebook",
  "invitations": {
    "href": "https://apps.cirrusidentity.com/console/api/v2/guest/2666957e-b1de-4e16-a301-a32bacfaa091/invitations"
  }
}

Here is the response that would be returned from a request where the UID was not found

HTTP/1.1 404

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Wed, 17 Jan 2018 21:27:51 GMT
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 83
Connection: keep-alive

{
  "errors": [
    "Guest not found for uid: 2666957e-b1de-4e16-a301-a32bacfaa091-dummy."
  ]
}

CREATE Guest

uri	/guests
description	Create a guest in a linkGroup. You can use this as an anchor for different providerAttributes -- this is used to support authentication based account linking
http operation	POST
success response	201
error response	403 authentication/authorization error

Required Parameters

Name	Description	Format
givenName	The given name for the guest	String
sn	The surname for the guest	String
mail	The email address for the guest	RFC 4524
linkGroup	A valid linkGroupId provide by the /linkGroups API	Numeric; Must be >= 0

Optional Parameters

Name	Description	Format
None

Sample Request

The following is a valid request which contains all required parameters.

curl --location --request POST "https://apps.cirrusidentity.com/console/api/v2/guests" \

  --header "Content-Type: application/json" \
  --data "{
    \"givenName\": \"Alice\",
    \"sn\": \"Arcus\",
    \"mail\": \"alice.arcus@outlook.com\",
     \"linkGroup\": {
                \"id\": \"99991\"
     }
}"

Sample Response

Here is the response that would be returned from the previous request.

HTTP/1.1 201 Created

Date: Fri, 21 Dec 2018 20:38:36 GMT
Content-Type: application/json;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: AWSALB=REDACTED
X-Application-Context: REDACTED
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Location: https://apps.cirrusidentity.com/console/api/v2/guest/aaaaaaa-bbbb-4444-cccc-111111111111
Set-Cookie: JSESSIONID=REDACTED

{
  "href": "https://apps.cirrusidentity.com/console/api/v2/guest/aaaaaaa-bbbb-4444-cccc-111111111111",
  "givenName": "Alice",
  "sn": "Arcus",
  "uid": "aaaaaaa-bbbb-4444-cccc-111111111111",
  "mail": "alice.arcus@outlook.com",
  "domain": "athena-institute.net",
  "status": "valid",
  "expirationDate": null,
  "createDate": "2018-12-21T20:38:36Z",
  "modifyDate": "2018-12-21T20:38:36Z",
  "eduPersonPrincipalName": null,
  "customData": {},
  "socialProvider": "",
  "invitations": {
    "href": "https://apps.cirrusidentity.com/console/api/v2/guest/aaaaaaa-bbbb-4444-cccc-111111111111/invitations"
  }
}

Delete Guest

uri	/guest/{uid}
description	Delete a guest object
http operation	DELETE
success response	200
error response	403 authentication/authorization error 404 UID not found or delete not allowed

Required Parameters

Name	Description	Format
UID	The uid assigned to the guest record.	string

Optional Parameters

Name	Description	Format
None

Sample Request

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

curl -i -u {api_key}:{api_secret} -X DELETE \
https://apps.cirrusidentity.com/console/api/v2/guest/{uid}

Errors

The API will return errors if there is are either active invitation or provider attribute (linking) records
attached to the guest.

{
  "errors": [
    "Guest has linked provider attributes and cannot be deleted."
  ]
}

{
  "errors": [
    "Guest has existing invitation(s) and cannot be deleted."
  ]
}

GET Sponsor

uri	/sponsor/{uid}
description	Return the attributes for a sponsor.
http operation	GET
success response	200
error response	403 authentication/authorization error 404 UID not found

Required Parameters

Name	Description	Format
UID	The uid assigned to the sponsor record.	string

Optional Parameters

Name	Description	Format
None

Sample Request

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

curl -i -u {api_key}:{api_secret} \

https://apps.cirrusidentity.com/console/api/v2/sponsor/{uid}

Sample Response

Here is the response that would be returned from the sample request.

HTTP/1.1 200 
Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Wed, 17 Jan 2018 21:29:42 GMT
Set-Cookie: JSESSIONID=***REDACT***
Set-Cookie: AWSELB=***REDACT***
Content-Length: 316
Connection: keep-alive

{
  "href": "https://apps.cirrusidentity.com/console/api/v2/sponsor/11aa22bb33cc44dd55ee66ff77aa88bb",
  "givenName": "Someone",
  "sn": "Sponsor",
  "uid": "11aa22bb33cc44dd55ee66ff77aa88bb",
  "mail": "someone.sponsor@athena-institute.net",
  "eppn": "someone.sponsor@athena-institute.net",
  "createDate": "2017-04-19T21:38:50Z",
  "modifyDate": "2018-01-16T14:16:00Z"
}

Here is the response that would be returned from a request where the UID is not found.

HTTP/1.1 404

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Wed, 17 Jan 2018 21:36:33 GMT
Set-Cookie: JSESSIONID=***REDACTED**
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 81
Connection: keep-alive

{
  "errors": [
    "Sponsor not found for uid: 11aa22bb33cc44dd55ee66ff77aa88bb-dummy."
  ]
}

View full post