Jul 6, 2022 12:00:00 PM

Invitation Endpoints

List Invitations for a Domain

uri	/invitations/{domain}
description	Paginated listing of all the invitations 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 invitations.	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.
status	Filter the invitations returned by their status. Possible values: pending, invited, processing-invite, claimed, and expired Status Definitions: invited: The invitation email has been sent, but the request URL has not been clicked on pending: The invitation request has been clicked, but binding to social login is not complete processing-invite: The invitation is pending an email address verification claimed: The invitation has been successfully claimed expired: The invitation was not claimed before the expiration time	String.
mailForInvite	An optional search parameter to return invitations based on the email address the invitation was sent to.	RFC 4524
type	An optional search parameter to return invitations 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: INVITATION: When the invitation was sent INVITATION_ACCEPTED: When the invitation was accepted EXPIRATION: When the time-to-live (ttl) for the invitation 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'

Sample Request

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

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

-d offset=10 \
-d limit=5 \
https://apps.cirrusidentity.com/console/api/v2/invitations/{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 16:06:45 GMT
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 4522
Connection: keep-alive

{

    "href": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net?offset=10&amp;limit=5",
    "totalCount": 277,
    "offset": 10,
    "limit": 5,
    "count": 5,
    "first": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net?offset=0&amp;limit=5",
    "next": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net?offset=15&amp;limit=5",
    "prev": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net?offset=5&amp;limit=5",
    "invitations": [
        {
            "href": "https://apps.cirrusidentity.com/console/api/v2/invitation/3d445365-3ea6-4aa8-9dd7-a062ab62e244",
            "uid": "3d445365-3ea6-4aa8-9dd7-a062ab62e244",
            "createDate": "2017-11-08T21:02:37Z",
            "modifyDate": "2017-12-06T19:26:55Z",
            "mailForInvite": "ted.thunder@athena-institute.net",
            "status": "expired",
            "invitationDate": "2017-11-08T21:02:37Z",
            "invitationAcceptedDate": "2017-11-08T21:28:25Z",
            "expirationDate": "2017-12-06T19:26:55Z",
            "validityPeriod": 3,
            "givenName": "",
            "sn": "",
            "customData": {
                "course": "dummy",
                "section": "dummy"
            },
            "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/2b810448-cbbe-42b0-b580-122211485f6a"
            }
        },
        {
            "href": "https://apps.cirrusidentity.com/console/api/v2/invitation/83fd16b5-22c5-41a5-9dac-7b72193060c9",
            "uid": "83fd16b5-22c5-41a5-9dac-7b72193060c9",
            "createDate": "2017-11-08T21:38:05Z",
            "modifyDate": "2017-11-08T22:00:47Z",
            "mailForInvite": "ted.thunder@athena-institute.net",
            "status": "claimed",
            "invitationDate": "2017-11-08T21:38:05Z",
            "invitationAcceptedDate": "2017-11-08T22:00:47Z",
            "expirationDate": "2018-11-08T21:38:05Z",
            "validityPeriod": 3,
            "givenName": "",
            "sn": "",
            "customData": {
                "course": "MATH1",
                "section": "SEC1"
            },
            "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/c95cb98e-2a1a-4837-b71e-522d7e5c00e2"
            }
        },
        ...
    ]
}

To list invitations with a specific status, add the parameter "status" to the request. For example:

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

-d offset=10 \
-d limit=5 \
-d status=invited \
https://apps.cirrusidentity.com/console/api/v2/invitations/{domain}

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 Invitations by Custom Attribute

uri	/invitations/{domain}/byCustomAttribute
description	Get invitations 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 invitations.	rfc1035
attributeName	The invitation 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 and some of the optional parameters.

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

-d attributeName='course' \
-d attributeValue='Course1' \
https://apps.cirrusidentity.com/console/api/v2/invitations/{domain}/byCustomAttribute

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, 09 Feb 2018 23:05:04 GMT
Server: Apache
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 1004
Connection: keep-alive

{

  "href": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net/byCustomAttribute?attributeName=course&attributeValue=Course1",
  "totalCount": 1,
  "count": 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-29T22:40:02Z",
      "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",
        "inviteID": "I9876"
      },
      "spEntityID": "https://research.athena-institute.net/shibboleth",
      "sponsor": {
        "href": "https://apps.cirrusidentity.com/console/api/v2/sponsor/49752181d026498eaba185ec41fd9b66"
      },
      "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 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 200

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Fri, 09 Feb 2018 23:21:07 GMT
Server: Apache
Set-Cookie: JSESSIONID=**REDACTED**
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 196
Connection: keep-alive

{
  "href": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net/byCustomAttribute?attributeName=course&attributeValue=Dummy",
  "totalCount": 0,
  "count": 0,
  "invitations": []
}

Get Invitation

uri	/invitation/{uid}
description	Return the attributes for an invitation.
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 invitation.	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/invitation/{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:48:24 GMT
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 808
Connection: keep-alive

{

  "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:54:02 GMT
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 88
Connection: keep-alive

{
  "errors": [
    "Invitation not found for uid: ac80d916-7918-4887-a9df-d158416a5601-dummy."
  ]
}

Put Invitation Custom Data

uri	/invitation/{uid}/customData
description	Update the customData name-value pairs for an invitation.
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 invitation 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 "newID" to the customData and retaining the existing "course" and "inviteID" entries.

curl -i -u {api_key}:{api_secret} \
-X PUT \
-H 'Content-Type: application/json' \
-d '{ "customData": {"course": "Course1", "inviteID": "I9876", "newID": "N999"}}' \
https://apps.cirrusidentity.com/console/api/v2/invitation/ac80d916-7918-4887-a9df-d158416a5601/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: Fri, 09 Feb 2018 23:31:23 GMT
Server: Apache
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 821
Connection: keep-alive

{

  "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-29T22:40:02Z",
  "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",
    "newID": "N999",
    "inviteID": "I9876"
  },
  "spEntityID": "https://research.athena-institute.net/shibboleth",
  "sponsor": {
    "href": "https://apps.cirrusidentity.com/console/api/v2/sponsor/49752181d026498eaba185ec41fd9b66"
  },
  "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 was not found

HTTP/1.1 404

Cache-control: no-cache="set-cookie"
Content-Type: application/json;charset=UTF-8
Date: Fri, 09 Feb 2018 23:35:50 GMT
Server: Apache
Set-Cookie: JSESSIONID=***REDACTED***
Set-Cookie: AWSELB=***REDACTED***
Content-Length: 77
Connection: keep-alive

{
  "errors": [
    "Invitation not found for uid: (ac80d916-7918-4887-a9df-dummy)."
  ]
}

Invitation Endpoints

List Invitations for a Domain

Required Parameters

Optional Parameters

Sample Request

Sample Response

Get Invitations by Custom Attribute

Required Parameters

Optional Parameters

Sample Request

Sample Response

Get Invitation

Required Parameters

Optional Parameters

Sample Request

Sample Response

Put Invitation Custom Data

Required Parameters

Optional Parameters

Sample Request

Sample Response

Blog comments

Related posts

Guest and Sponsor Endpoints

Link Group and Provider Attribute Endpoints

Overview- API v2 Basics

Why Cirrus?

Solutions

Products

Customers

Company

Resources