Guest and Sponsor Endpoints

 

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&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&limit=5",
    "prev": "https://apps.cirrusidentity.com/console/api/v2/guests/athena-institute.net?offset=5&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&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&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&attributeValue=A1234-dummy","totalCount":0,"count":0,"guests":[]}
 

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

 

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

© Copyright Cirrus Identity, Inc.

Blog comments