Documentation

Invitation Endpoints

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

 

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&limit=5",
    "totalCount": 277,
    "offset": 10,
    "limit": 5,
    "count": 5,
    "first": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net?offset=0&limit=5",
    "next": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net?offset=15&limit=5",
    "prev": "https://apps.cirrusidentity.com/console/api/v2/invitations/athena-institute.net?offset=5&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)."
  ]
}

© Copyright Cirrus Identity, Inc.
View full post