Overview- API v2 Basics

Overview

Version 2 of API uses a data model consisting of guests that have associated invitations. Each invitation will also have an associated sponsor. This allows guests to have multiple invitations. The endpoints currently available are as follows:

• Guest and Sponsor Endpoints
  • /guests/{domain}
  • /guests/{domain}/byCustomAttribute
  • /guest/{uid}
  • /guest/{uid}/invitations
  • /guest/{uid}/customData
  • /sponsor/{uid}
• Invitation Endpoints
  • /invitations/{domain}
  • /invitations/{domain}/byCustomAttribute
  • /invitation/{uid}
  • /invitation/{uid}/customData
• Link Groups and Provider Attributes
  • /linkGroups
  • /providerAttributes
  • /providerAttributes/{id}/attributes

Base URI

The base URI for the API:   

https://apps.cirrusidentity.com/console/api/v2

Authorization

The API uses HTTP Basic authentication (BA). Cirrus Identity will supply customers with a unique API key / API secret pair. If the authentication/authorization fails, an HTTP-403 response code is returned.

Here is a sample response from a request where the API key is not recognized

HTTP/1.1 403 

Cache-control: no-cache="set-cookie"
Content-Type: text/html;charset=utf-8
Date: Fri, 05 Jan 2018 04:12:27 GMT
Set-Cookie: AWSELB=**REDACTED**
transfer-encoding: chunked
Connection: keep-alive

{"errors":["API Authentication - Authentication failed; Invalid api key or password."]}

Here is a sample response from a request where the API secret is not recognized

HTTP/1.1 403 

Cache-control: no-cache="set-cookie"
Content-Type: text/html;charset=utf-8
Date: Fri, 05 Jan 2018 04:13:39 GMT
Set-Cookie: AWSELB=**REDACTED**
Content-Length: 75
Connection: keep-alive

{"errors":["API Authentication - Authentication failed; Invalid api key or password."]}

Requests

Data supplied in the body of a request (for example in an HTTP-PUT) must be in the form of a JSON document, and the Content-Type header should be set to application/json.

Responses

The response body will always be a JSON document containing either the result of a successful operation, or an errors object. Samples are provided for each endpoint.

If an operation is successful, the HTTP response code will be an appropriate 2xx code.

If the operation fails, an appropriate HTTP 4xx or 5xx response code will be returned, and an error will be provided in the response body.