Cirrus Identity Log API

v1.0.3

Base URL

/logs/v1

All endpoints require HTTP Basic authentication using Cirrus Identity Log API credentials, provisioned in the Cirrus Console.

`/logs/v1/orgUrls`

Returns a list of permitted orgUrls for the provided credentials.

`/logs/v1/orgLogs`

Returns logs for a specific orgUrl value. Expand the /orgLogs endpoint (below) for details on parameters and schema.

Authentication

HTTPBasichttp

Scheme: basic

Endpoints

Return Logs For A Specified Org Url

GET

/logs/v1/orgLogs

Returns an array of log events for the specified orgUrl value.

Query parameters

orgUrl (required): the organization URL for which to retrieve logs. This must match your organization URL from the Cirrus Console exactly, including any trailing /.
nextToken (optional): token returned from a previous call to URL, logs returned will start at the next record following the one referenced by this token. If not provided, logs returned will start at 1 hour ago from the current time.
limit (optional): a value between 1 - 1000 indicating the number of log events to return. Default is 1000.
filter parameters (all optional) -- these can be used to filter the results
- service: the service (e.g., proxy or bridge)
- logType: the log event type (e.g, authentication or cas)
- logSubtype: the log event sub-type (e.g., request or success)
- tenant: the tenant name

Rate Limiting

To avoid rate limiting, Cirrus Identity recommends a delay of at least five minutes between retrieval of sets of logs. For best results, consider enforcing this delay once the /orgLogs API response contains fewer log events than requested (via the limit parameter, up to the maximum of 1000 log events).

Parameters

orgUrlstring<uri>requiredquery

nextTokenstring<uuid>query

limitinteger<= 10001000query

logTypeLogTypesEnumaccountauthenticationcascreateemailMFAoidcpasswordsendingquery

logSubtypeLogSubtypesEnumauthenticationSuccessauthorizeerrorexpiredCodefailureidTokeninvalidCodeloginlogoutmanagenoEmailqueuedrequestsamlValidatesendsentserviceValidatesuccesstokenuserinfovalidatequery

tenantstringquery

serviceServiceTypesEnumbridgegatewayidGenerationidpmailproxyquery

Response

200OKLogApiResponse

Success

401Unauthorized

Authentication failed

403Forbidden

Unauthorized

422Unprocessable EntityHTTPValidationError

Validation Error

500Internal Server Error

Internal Server Error

Authorization

HTTPBasichttp (basic)

Return Logs For A Specified Org Url

curl -X GET '/logs/v1/orgLogs'

const response = await fetch('/logs/v1/orgLogs', {
  method: 'GET',
});

const data = await response.json();

import requests

response = requests.get('/logs/v1/orgLogs')
data = response.json()

{
  "ref": "https://api.cirrusidentity.com/logs/v1/orgLogs?orgUrl=http%3A%2F%2Finstitution.edu%2F",
  "next": "https://api.cirrusidentity.com/logs/v1/orgLogs?orgUrl=http%3A%2F%2Finstitution.edu%2F&nextToken=018ec539-2f4d-7e4c-9310-46ef060440a8",
  "nextToken": "018ec539-2f4d-7e4c-9310-46ef060440a8",
  "count": 1,
  "logEvents": [
    {
      "logType": "authentication",
      "timeStampISO": "2024-04-09T23:37:16+00:00",
      "orgDomain": "institution.edu",
      "service": "bridge",
      "clientIP": "1.2.3.4",
      "logSubtype": "request",
      "correlationId": "757769a369",
      "orgUrl": "http://institution.edu/",
      "tenant": "institution-bridge",
      "logData": {
        "spEntityId": "https://institution-bridge.proxy.cirrusidentity.com/bridge"
      }
    }
  ]
}

{
  "detail": "invalid API authentication"
}

{
  "detail": "Not authorized for org"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

{
  "detail": "unknown error"
}

Return Logs For A Specified Org Url

curl -X GET '/logs/v1/orgLogs'

const response = await fetch('/logs/v1/orgLogs', {
  method: 'GET',
});

const data = await response.json();

import requests

response = requests.get('/logs/v1/orgLogs')
data = response.json()

{
  "ref": "https://api.cirrusidentity.com/logs/v1/orgLogs?orgUrl=http%3A%2F%2Finstitution.edu%2F",
  "next": "https://api.cirrusidentity.com/logs/v1/orgLogs?orgUrl=http%3A%2F%2Finstitution.edu%2F&nextToken=018ec539-2f4d-7e4c-9310-46ef060440a8",
  "nextToken": "018ec539-2f4d-7e4c-9310-46ef060440a8",
  "count": 1,
  "logEvents": [
    {
      "logType": "authentication",
      "timeStampISO": "2024-04-09T23:37:16+00:00",
      "orgDomain": "institution.edu",
      "service": "bridge",
      "clientIP": "1.2.3.4",
      "logSubtype": "request",
      "correlationId": "757769a369",
      "orgUrl": "http://institution.edu/",
      "tenant": "institution-bridge",
      "logData": {
        "spEntityId": "https://institution-bridge.proxy.cirrusidentity.com/bridge"
      }
    }
  ]
}

{
  "detail": "invalid API authentication"
}

{
  "detail": "Not authorized for org"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

{
  "detail": "unknown error"
}

Return A List Of Permitted Org Urls

GET

/logs/v1/orgUrls

Returns an array of orgUrl values that the current authenticated user is permitted to use (in the orgUrl query parameter for the / endpoint) for retrieving logs.

Response

200OKany

Success

401Unauthorized

Authentication failed

500Internal Server Error

Internal Server Error

Authorization

HTTPBasichttp (basic)

Return A List Of Permitted Org Urls

curl -X GET '/logs/v1/orgUrls'

const response = await fetch('/logs/v1/orgUrls', {
  method: 'GET',
});

const data = await response.json();

import requests

response = requests.get('/logs/v1/orgUrls')
data = response.json()

{
  "orgUrls": [
    "http://www.institution.edu"
  ]
}

{
  "detail": "invalid API authentication"
}

{
  "detail": "unknown error"
}

Return A List Of Permitted Org Urls

curl -X GET '/logs/v1/orgUrls'

const response = await fetch('/logs/v1/orgUrls', {
  method: 'GET',
});

const data = await response.json();

import requests

response = requests.get('/logs/v1/orgUrls')
data = response.json()

{
  "orgUrls": [
    "http://www.institution.edu"
  ]
}

{
  "detail": "invalid API authentication"
}

{
  "detail": "unknown error"
}

Models

HTTPValidationError

object

detailArray<ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Example

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

LogApiResponse

object

wrapper response for log items

refstring<uri>required

the URL called to elicit this response

nextstring<uri>required

URL to call to retrieve next set of log events

nextTokenstring | null

token for retrieving next set of log events

countintegerrequired

number of log events returned in this response

logEventsArray<object>required

array of log event objects

Example

{
  "ref": "https://example.com",
  "next": "https://example.com",
  "nextToken": "550e8400-e29b-41d4-a716-446655440000",
  "count": 0,
  "logEvents": [
    {}
  ]
}

LogSubtypesEnum

string

enum for Cirrus log subtypes

LogSubtypesEnumauthenticationSuccessauthorizeerrorexpiredCodefailureidTokeninvalidCodeloginlogoutmanagenoEmailqueuedrequestsamlValidatesendsentserviceValidatesuccesstokenuserinfovalidate

Example

"authenticationSuccess"

LogTypesEnum

string

enum for Cirrus log types

LogTypesEnumaccountauthenticationcascreateemailMFAoidcpasswordsending

Example

"account"

ServiceTypesEnum

string

enum for valid Cirrus services

ServiceTypesEnumbridgegatewayidGenerationidpmailproxy

Example

"bridge"

ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Example

{
  "loc": [
    "string"
  ],
  "msg": "string",
  "type": "string"
}