Cirrus Identity OrgBrandedID Customer Notification API

Table of Contents

• Rationale

• Architecture

• API Details

• JSON Payload Format

• Security and Authentication

• Expected Behavior and Response

• Error Handling

• Timeouts and Retries

• Registering your OBID Customer Notification Endpoint

Rationale

The Cirrus Identity OrgBrandedID (OBID) Customer Notification API provides a mechanism, via a simple REST-based API specification, by which Cirrus customers may receive near real-time notifications of OBID account creation (“bootstrap”) and activation events.

Architecture

The Cirrus OBID service utilizes a persistent, transactional queuing mechanism to store messages containing the metadata associated with OBID account creation and activation events. An external service listens on this queue for new messages and, upon arrival, routes a JSON representation of the message to the registered endpoint for the message’s organizational domain – if a customer REST endpoint is registered for the organizational domain.

API Details

The customer must implement an endpoint service capable of receiving a JSON payload via an HTTP POST.

JSON Payload Format

There are 2 categories of “status” events for which customer notification messages will be generated:

• BOOTSTRAP (account has been created/initialized)

• ACTIVE (user has successfully activated account)

The format of messages is identical for both events, only the value of the status field will be different.

For an individual account, you will see the BOOTSTRAP message before the ACTIVE message, as the queuing mechanism (discussed in Architecture) uses FIFO semantics.

Example BOOTSTRAP payload:

Example ACTIVE payload:

Security and Authentication

• Customer REST endpoint must be directly accessible via HTTPS
• Authentication will be performed via the HTTP Basic authentication scheme
  • Credentials should be securely communicated to Cirrus Identity (e.g., via https://onetimesecret.com/ or similar mechanism)

Expected Behavior and Response

The customer REST endpoint should ensure that it responds in less than 60 seconds in order to prevent a timeout on the Cirrus side, which will result in requeuing/redelivery.

The customer REST endpoint should respond with an HTTP 200 status code if the message has been received successfully. Any other status code will result in the message being requeued/redelivered on the Cirrus side. No HTTP response body needs to be included in the response (and will be ignored).

Error Handling

The notification message remains on the queue until one of the following is true:

• The organizational domain in the message does not have a registered customer REST endpoint (in which case the message is simply discarded)
• The message is successfully delivered to the customer REST endpoint (see Expected Behavior and Response).
• The maximum number of re-queue/redelivery attempts is reached

Timeouts and Retries

• Connection to the customer REST endpoint (prior to sending data): 500ms
• Read timeout (waiting for customer REST endpoint to respond after sending data): 60s
• Delay between requeue/retry attempts (e.g., if customer REST endpoint returns an error or is not reachable): 90s
• Maximum number of requeue/retry attempts: 40
  • Upon exhaustion of requeue/retry attempts, the message will be moved to a “dead letter queue”, where it will live for up to 2 weeks
    • Cirrus Operations will also receive an alert notification when any messages are moved to the dead letter queue

Registering your OBID Customer Notification Endpoint

Once you have implemented your REST endpoint, per the specifications above, please communicate the following details to Cirrus Customer Success:

• The URL of your REST endpoint
• The HTTP Basic authentication scheme credentials (username & password) used to authenticate to your API. Please communicate these securely, as described in Security and Authentication.
• The events for which you wish to receive notifications at your REST endpoint. You may choose to receive either or both:
• BOOTSTRAP
• ACTIVE
• When you wish to begin receiving notifications at your REST endpoint