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).

Return Logs For A Specified Org Url

BASE_URL='YOUR_API_ORIGIN'
curl -X GET "${BASE_URL}"'/logs/v1/orgLogs?orgUrl=https%3A%2F%2Fexample.com&limit=1000' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE'

const baseUrl = 'YOUR_API_ORIGIN';
const response = await fetch(baseUrl + '/logs/v1/orgLogs?orgUrl=https%3A%2F%2Fexample.com&limit=1000', {
  method: 'GET',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
  },
});

const data = await response.text();

import requests

base_url='YOUR_API_ORIGIN'
response = requests.get(
    base_url + '/logs/v1/orgLogs?orgUrl=https%3A%2F%2Fexample.com&limit=1000',
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    },
)
print(response.text)

{
  "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",
      "ctx": {}
    }
  ]
}

{
  "detail": "unknown error"
}

Parameters

orgUrlstring<uri>requiredquery

nextTokenstring<uuid>query

limitinteger<= 10001000query

logTypeLogTypesEnumaccountauthenticationcascreateemailMFAoidcpasswordsendingquery

logSubtypeLogSubtypesEnumauthenticationSuccessauthorizeerrorexpiredCodefailureidTokeninvalidCodeloginlogoutmanagenoEmailqueuedrequestsamlValidatesendsentserviceValidatesuccesstokenuserinfovalidatequery

tenantstringquery

serviceServiceTypesEnumbridgegatewayidGenerationidpmailproxyquery

Response

200OKLogApiResponse

Success

Response fields application/json

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

Show child attributes

Any of

string<uuid>

null

countintegerrequired

number of log events returned in this response

logEventsArray<object>required

array of log event objects

401Unauthorized

Authentication failed

403Forbidden

Unauthorized

422Unprocessable EntityHTTPValidationError

Validation Error

Response fields application/json

detailArray<ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

500Internal Server Error

Internal Server Error

Authorization

HTTPBasichttp (basic)

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.

Return A List Of Permitted Org Urls

BASE_URL='YOUR_API_ORIGIN'
curl -X GET "${BASE_URL}"'/logs/v1/orgUrls' \
  -H 'Authorization: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE'

const baseUrl = 'YOUR_API_ORIGIN';
const response = await fetch(baseUrl + '/logs/v1/orgUrls', {
  method: 'GET',
  headers: {
    'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
  },
});

const data = await response.text();

import requests

base_url='YOUR_API_ORIGIN'
response = requests.get(
    base_url + '/logs/v1/orgUrls',
    headers={
        'Authorization': 'Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE',
    },
)
print(response.text)

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

{
  "detail": "invalid API authentication"
}

{
  "detail": "unknown error"
}

Response

200OKany

Success

Response fields application/json

any

401Unauthorized

Authentication failed

500Internal Server Error

Internal Server Error

Authorization

HTTPBasichttp (basic)

Models

HTTPValidationError

object

detailArray<ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

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

Show child attributes

Any of

string<uuid>

null

countintegerrequired

number of log events returned in this response

logEventsArray<object>required

array of log event objects

LogSubtypesEnum

string

enum for Cirrus log subtypes

LogSubtypesEnumauthenticationSuccessauthorizeerrorexpiredCodefailureidTokeninvalidCodeloginlogoutmanagenoEmailqueuedrequestsamlValidatesendsentserviceValidatesuccesstokenuserinfovalidate

LogTypesEnum

string

enum for Cirrus log types

LogTypesEnumaccountauthenticationcascreateemailMFAoidcpasswordsending

ServiceTypesEnum

string

enum for valid Cirrus services

ServiceTypesEnumbridgegatewayidGenerationidpmailproxy

ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject