The endpoints API from Cirrus Identity — 2 operation(s) for endpoints.
openapi: 3.1.0
info:
title: Cirrus Identity Log endpoints API
description: "\nAll endpoints require HTTP Basic authentication using\n[Cirrus Identity Log API credentials](https://blog.cirrusidentity.com/documentation/log-api-credentials),\nprovisioned in the Cirrus Console. \n\n## `/logs/v1/orgUrls`\n\nReturns a list of permitted `orgUrls` for the provided credentials.\n\n## `/logs/v1/orgLogs`\n\nReturns logs for a specific `orgUrl` value. Expand the `/orgLogs` endpoint (below)\nfor details on parameters and schema.\n"
version: 1.0.3
servers:
- url: /logs/v1
tags:
- name: endpoints
paths:
/orgLogs:
get:
tags:
- endpoints
summary: Return logs for a specified orgUrl
description: "Returns an array of log events for the specified `orgUrl` value.\n\n### Query parameters\n\n- `orgUrl` (**required**): the organization URL for which to retrieve logs. This must match\n your organization URL from the Cirrus Console _**exactly**_, including any trailing `/`.\n- `nextToken` (optional): token returned from a previous call to URL, logs returned\n will start at the next record following the one referenced by this token. If not provided,\n logs returned will start at 1 hour ago from the current time.\n- `limit` (optional): a value between 1 - 1000 indicating the number of log events to return.\n Default is 1000.\n- filter parameters (all optional) -- these can be used to filter the results\n - `service`: the service (e.g., *proxy* or *bridge*)\n - `logType`: the log event type (e.g, *authentication* or *cas*)\n - `logSubtype`: the log event sub-type (e.g., *request* or *success*)\n - `tenant`: the tenant name\n\n### Rate Limiting\n\nTo avoid rate limiting, Cirrus Identity recommends a delay of at least five minutes between\nretrieval of sets of logs. For best results, consider enforcing this delay once the `/orgLogs`\nAPI response contains fewer log events than requested (via the `limit` parameter, up to the\nmaximum of 1000 log events)."
operationId: get_org_logs
security:
- HTTPBasic: []
parameters:
- name: orgUrl
in: query
required: true
schema:
type: string
format: uri
minLength: 1
title: Orgurl
- name: nextToken
in: query
required: false
schema:
type: string
format: uuid
title: Nexttoken
- name: limit
in: query
required: false
schema:
type: integer
maximum: 1000
exclusiveMinimum: 0
default: 1000
title: Limit
- name: logType
in: query
required: false
schema:
$ref: '#/components/schemas/LogTypesEnum'
- name: logSubtype
in: query
required: false
schema:
$ref: '#/components/schemas/LogSubtypesEnum'
- name: tenant
in: query
required: false
schema:
type: string
title: Tenant
- name: service
in: query
required: false
schema:
$ref: '#/components/schemas/ServiceTypesEnum'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/LogApiResponse'
example:
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
'401':
description: Authentication failed
content:
application/json:
example:
detail: invalid API authentication
'403':
description: Unauthorized
content:
application/json:
example:
detail: Not authorized for org
'500':
description: Internal Server Error
content:
application/json:
example:
detail: unknown error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/orgUrls:
get:
tags:
- endpoints
summary: Return a list of permitted orgUrls
description: '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.'
operationId: get_orgs
responses:
'200':
description: Success
content:
application/json:
schema: {}
example:
orgUrls:
- http://www.institution.edu
'401':
description: Authentication failed
content:
application/json:
example:
detail: invalid API authentication
'500':
description: Internal Server Error
content:
application/json:
example:
detail: unknown error
security:
- HTTPBasic: []
components:
schemas:
LogApiResponse:
properties:
ref:
type: string
minLength: 1
format: uri
title: Ref
description: the URL called to elicit this response
next:
type: string
minLength: 1
format: uri
title: Next
description: URL to call to retrieve next set of log events
nextToken:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Nexttoken
description: token for retrieving next set of log events
count:
type: integer
title: Count
description: number of log events returned in this response
logEvents:
items:
type: object
type: array
title: Logevents
description: array of log event objects
type: object
required:
- ref
- next
- count
- logEvents
title: LogApiResponse
description: wrapper response for log items
LogSubtypesEnum:
type: string
enum:
- authenticationSuccess
- authorize
- error
- expiredCode
- failure
- idToken
- invalidCode
- login
- logout
- manage
- noEmail
- queued
- request
- samlValidate
- send
- sent
- serviceValidate
- success
- token
- userinfo
- validate
title: LogSubtypesEnum
description: enum for Cirrus log subtypes
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
LogTypesEnum:
type: string
enum:
- account
- authentication
- cas
- create
- emailMFA
- oidc
- password
- sending
title: LogTypesEnum
description: enum for Cirrus log types
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ServiceTypesEnum:
type: string
enum:
- bridge
- gateway
- idGeneration
- idp
- mail
- proxy
title: ServiceTypesEnum
description: enum for valid Cirrus services
securitySchemes:
HTTPBasic:
type: http
scheme: basic