# Cirrus Identity Log API

All endpoints require HTTP Basic authentication using
[Cirrus Identity Log API credentials](https://blog.cirrusidentity.com/documentation/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.


Version: 1.0.3

Authentication:
- HTTPBasic: http (basic)

## Return Logs For A Specified Org Url

`GET /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).

Authentication (security requirement alternatives):

```json
[
  {
    "HTTPBasic": []
  }
]
```

- HTTPBasic: http (basic)

Parameters:

- `orgUrl` (query, string, uri, required)
  Type: string, uri
  
  minLength: 1
  
  maxLength: 2083

- `nextToken` (query, string, uuid, optional)
  Type: string, uuid

- `limit` (query, integer, optional)
  Type: integer
  
  default: 1000
  
  maximum: 1000
  
  exclusiveMinimum: 0

- `logType` (query, LogTypesEnum, optional)
  Type: LogTypesEnum
  
  enum for Cirrus log types
  
  Schema: [LogTypesEnum](/log-api/schemas/logtypesenum-ce17276e5a.md)
  
  enum: ["account","authentication","cas","create","emailMFA","oidc","password","sending"]

- `logSubtype` (query, LogSubtypesEnum, optional)
  Type: LogSubtypesEnum
  
  enum for Cirrus log subtypes
  
  Schema: [LogSubtypesEnum](/log-api/schemas/logsubtypesenum-a9636c87c6.md)
  
  enum: ["authenticationSuccess","authorize","error","expiredCode","failure","idToken","invalidCode","login","logout","manage","noEmail","queued","request","samlValidate","send","sent","serviceValidate","success","token","userinfo","validate"]

- `tenant` (query, string, optional)
  Type: string

- `service` (query, ServiceTypesEnum, optional)
  Type: ServiceTypesEnum
  
  enum for valid Cirrus services
  
  Schema: [ServiceTypesEnum](/log-api/schemas/servicetypesenum-00c819aa6a.md)
  
  enum: ["bridge","gateway","idGeneration","idp","mail","proxy"]

Responses:

- 200: Success

Content type: application/json

Type: LogApiResponse

wrapper response for log items

Schema: [LogApiResponse](/log-api/schemas/logapiresponse-a0e0371ebe.md)

- `ref` (required)
  Type: string, uri
  
  the URL called to elicit this response
  
  minLength: 1

- `next` (required)
  Type: string, uri
  
  URL to call to retrieve next set of log events
  
  minLength: 1

- `nextToken` (optional)
  Type: string | null
  
  token for retrieving next set of log events
  
  anyOf:
    Type: string, uuid
  
    Type: null

- `count` (required)
  Type: integer
  
  number of log events returned in this response

- `logEvents` (required)
  Type: Array<object>
  
  array of log event objects
  
  Items:
    Type: object
    
    Additional properties: true

```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"
      }
    }
  ]
}
```

- 401: Authentication failed

Content type: application/json

```json
{
  "detail": "invalid API authentication"
}
```

- 403: Unauthorized

Content type: application/json

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

- 422: Validation Error

Content type: application/json

Type: HTTPValidationError

Schema: [HTTPValidationError](/log-api/schemas/httpvalidationerror-231eeffce0.md)

- `detail` (optional)
  Type: Array<ValidationError>
  
  Items:
    Reference: [ValidationError](/log-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError

- 500: Internal Server Error

Content type: application/json

```json
{
  "detail": "unknown error"
}
```

## Examples

### cURL

```bash
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'
```

### JavaScript

```javascript
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();
```

### Python

```python
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)
```


## Return A List Of Permitted Org Urls

`GET /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.

Authentication (security requirement alternatives):

```json
[
  {
    "HTTPBasic": []
  }
]
```

- HTTPBasic: http (basic)

Responses:

- 200: Success

Content type: application/json

Type: any

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

- 401: Authentication failed

Content type: application/json

```json
{
  "detail": "invalid API authentication"
}
```

- 500: Internal Server Error

Content type: application/json

```json
{
  "detail": "unknown error"
}
```

## Examples

### cURL

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

### JavaScript

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

const data = await response.text();
```

### Python

```python
import requests

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


## HTTPValidationError

Type: HTTPValidationError

Schema: [HTTPValidationError](/log-api/schemas/httpvalidationerror-231eeffce0.md)

- `detail` (optional)
  Type: Array<ValidationError>
  
  Items:
    Reference: [ValidationError](/log-api/schemas/validationerror-bdfaef14be.md); Type: ValidationError

## LogApiResponse

Type: LogApiResponse

wrapper response for log items

Schema: [LogApiResponse](/log-api/schemas/logapiresponse-a0e0371ebe.md)

- `ref` (required)
  Type: string, uri
  
  the URL called to elicit this response
  
  minLength: 1

- `next` (required)
  Type: string, uri
  
  URL to call to retrieve next set of log events
  
  minLength: 1

- `nextToken` (optional)
  Type: string | null
  
  token for retrieving next set of log events
  
  anyOf:
    Type: string, uuid
  
    Type: null

- `count` (required)
  Type: integer
  
  number of log events returned in this response

- `logEvents` (required)
  Type: Array<object>
  
  array of log event objects
  
  Items:
    Type: object
    
    Additional properties: true

## LogSubtypesEnum

Type: LogSubtypesEnum

enum for Cirrus log subtypes

Schema: [LogSubtypesEnum](/log-api/schemas/logsubtypesenum-a9636c87c6.md)

enum: ["authenticationSuccess","authorize","error","expiredCode","failure","idToken","invalidCode","login","logout","manage","noEmail","queued","request","samlValidate","send","sent","serviceValidate","success","token","userinfo","validate"]

## LogTypesEnum

Type: LogTypesEnum

enum for Cirrus log types

Schema: [LogTypesEnum](/log-api/schemas/logtypesenum-ce17276e5a.md)

enum: ["account","authentication","cas","create","emailMFA","oidc","password","sending"]

## ServiceTypesEnum

Type: ServiceTypesEnum

enum for valid Cirrus services

Schema: [ServiceTypesEnum](/log-api/schemas/servicetypesenum-00c819aa6a.md)

enum: ["bridge","gateway","idGeneration","idp","mail","proxy"]

## ValidationError

Type: ValidationError

Schema: [ValidationError](/log-api/schemas/validationerror-bdfaef14be.md)

- `loc` (required)
  Type: Array<string | integer>
  
  Items:
    Type: string | integer
    
    anyOf:
      Type: string
    
      Type: integer

- `msg` (required)
  Type: string

- `type` (required)
  Type: string

- `input` (optional)
  Type: any

- `ctx` (optional)
  Type: object