1Password Audit log API

openapi: 3.2.0
info:
  title: SaaS Manager Audit log API
  description: 'By accessing or using 1Password Developer Tools, you agree to the API and SDK Terms of Service. ---


    The SaaS Manager public REST API lets you read and manage your applications, people, teams, contracts, devices, workflows and audit log programmatically. Resources are grouped by area (see the navigation). The conventions below apply across the whole API. ## Regions and base URL


    SaaS Manager is hosted in multiple regions. Pick the base URL for your tenant''s region from the **Servers** dropdown — `https://app.trelica.com` (United States) or `https://eu.trelica.com` (Europe). Endpoint URLs throughout this reference use whichever server you select. ## Authentication


    Every request must send an `Authorization` header carrying an OAuth 2.0 access token, prefixed with `Bearer`:


    ```

    Authorization: Bearer

    ```


    Obtain a token using either the **Client Credentials** flow (machine-to-machine) or the **Authorization Code** flow (acting on behalf of a user). The scopes granted to your token determine which endpoints you may call — see Scopes. Access tokens expire. When a token is missing, invalid or expired you receive `401 Unauthorized`; inspect the `WWW-Authenticate` response header for detail, for example:


    ```

    Bearer error="invalid_token", error_description="The token expired at ''12/23/2020 10:27:15''"

    ```


    If you used the Authorization Code flow with the `offline_access` scope, use your refresh token to obtain a new access token. A `403 Forbidden` means the token is valid but lacks the scope required by the endpoint. ## Dates and times


    Dates and date/times are sent and returned in RFC 3339 format (essentially ISO 8601), for example `2020-12-25` (midnight) or `2020-12-25T10:50:00Z`. Field names ending in `Dtm` carry a meaningful time component; field names ending in `Date` are date-only. ## Optional fields and null


    Responses omit fields that have no value — you will see the field absent rather than returned as `null`. When creating or replacing a resource (`PUT`), any field you omit is cleared. With `PATCH`, omitting a field leaves it unchanged, whereas sending it as `null` clears it. ## Pagination


    List endpoints are paginated and return at most 100 results by default. Request a different upper bound with the `limit` query parameter (maximum 1000) — you may receive fewer than requested. Request the next page with the `after` query parameter, passing the opaque cursor token that SaaS Manager supplies. The response''s `next` field (and the `link` response header, `rel="next"`) contains the full URL for the next page:


    ```json

    {

    "next": "https://app.trelica.com/api/people/v1?after=&limit=100",

    "results": [ { /* ... */ } ]

    }

    ```


    Keep requesting pages until no further results are returned. (User data exposed over SCIM uses the SCIM `startIndex`/`count` pagination scheme instead.)


    ## Filtering


    Many list endpoints accept a `filter` query parameter (URL-encoded) based on the SCIM filtering specification. A filter is one or more expressions — an attribute name, an operator, and an optional value — combined with `and`, `or`, `not`, and grouped with parentheses. Attribute names match the JSON returned and may use dot notation for nested attributes

    (e.g. `createdBy.email`). For an attribute that is an **array of objects**, put a sub-expression in

    brackets — the item matches when *any* element satisfies it: `teams[name eq "Developers"]` or

    `teams[id eq "5f8d0a1b2c3d4e5f60718293"]`. Values are strings (double-quoted), integers, dates

    (double-quoted, RFC 3339) or booleans. Some list endpoints also accept a free-text `q` parameter

    that searches the resource''s displayable fields. Soft-deleted entities are excluded by default; include them with a filter that references `deleted` (e.g. `filter=deleted eq true`).'
  contact:
    name: 1Password SaaS Manager Support
    email: saasmanager@1password.com
  version: v1
servers:
- url: https://app.trelica.com
  description: United States
- url: https://eu.trelica.com
  description: Europe
tags:
- name: Audit Log
  description: 'Read your organization''s audit log: a continuous, filterable stream of events.'
paths:
  /api/audit/v1/logs:
    get:
      tags:
      - Audit Log
      summary: List audit log events
      description: 'Returns audit log events for your organization, oldest first.


        The audit log is a continuous, append-only stream. Pagination is cursor-based but differs

        from the rest of the SaaS Manager API: the response''s `next` field (and the `link` response

        header, `rel="next"`) always returns a cursor URL — even on the last page — so you can keep

        following it to receive new events as they are written. Page until no further `results` are

        returned, then poll the same `next` URL periodically to pick up new events.


        Narrow results with `since`/`until` (a time window — by default the last 7 days),

        a SCIM-style `filter` (all operators except `[ ]`), or a free-text `q` query (matches the

        actor/target name, target email, and exactly matches event ID, event type, target ID and

        target type). Use `sortOrder=DESCENDING` to return newest events first. `limit` defaults to

        100 (maximum 1000).'
      parameters:
      - name: filter
        in: query
        description: 'A SCIM-style filter expression restricting the items returned. See the Filtering section of the introduction for the operators and syntax; the filterable fields are listed per resource.


          **Filterable fields**


          - **string:** `actor.alternateId`, `actor.detail`, `actor.displayName`, `actor.id`, `actor.type`, `client.ipAddress`, `details`, `eventType`, `target.alternateId`, `target.displayName`, `target.id`, `target.type`

          - **number:** `id`, `uuid`

          - **date:** `published`



          **Filter examples**


          - `eventType eq "employee_login_success"` — Successful login events

          - `eventType sw "integration_"` — All integration-related events

          - `actor.alternateId eq "john.doe@example.com"` — Events performed by this user

          - `target.type eq "CustomerApp"` — Events whose target is an application

          - `client.ipAddress eq "142.214.38.15"` — Events originating from this IP address

          - `published ge "2024-01-01"` — Events published on or after 1 Jan 2024'
        schema:
          type: string
      - name: q
        in: query
        description: Free-text search across the resource's displayable fields.
        schema:
          type: string
      - name: since
        in: query
        description: Only return items modified at or after this ISO-8601 timestamp.
        schema:
          type: string
          format: date-time
      - name: until
        in: query
        description: Only return items modified at or before this ISO-8601 timestamp.
        schema:
          type: string
          format: date-time
      - name: after
        in: query
        description: Opaque pagination cursor supplied by SaaS Manager via the `link` response header and the `next` field.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of items to return per page (default 100, maximum 1000).
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogEvents'
              example:
                next: https://acme.example.com/api/audit/v1/logs?after=eyJpZCI6NTQyMTR9&limit=100
                results:
                - id: 54214
                  published: '2020-12-22T09:09:01Z'
                  eventType: employee_login_success
                  client:
                    ipAddress: 142.214.38.15
                  target:
                  - id: 2dad1a642e744168c26b981ebfc1383f
                    type: User
                    displayName: John Doe
                    alternateId: john.doe@example.com
                  details:
                    method: password
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: One or more validation errors occurred.
                status: 400
                detail: The request body failed validation. See errors for the offending fields.
                errors:
                  email:
                  - The email field is required.
                traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
      operationId: getApiAuditV1Logs
      x-operation-id-source: derived
components:
  schemas:
    LogEventTarget:
      type: object
      properties:
        id:
          type: string
          description: The SaaS Manager ID of the target.
        type:
          type: string
          description: The type of the target, e.g. "User", "CustomerIntegration", "CustomerApp" or "ApiClient".
        displayName:
          type: string
          description: The display name of the target.
        alternateId:
          type: string
          description: An alternate identifier for the target, typically the target's email address.
      additionalProperties: false
    LogEvent:
      type: object
      properties:
        id:
          type: integer
          description: The SaaS Manager ID for the event.
          format: int64
        published:
          type: string
          description: The date and time the event occurred.
          format: date-time
        eventType:
          type: string
          description: The event type, e.g. "employee_login_success". See the list of event types in the documentation.
        actor:
          allOf:
          - $ref: '#/components/schemas/LogEventActor'
          description: The user who performed the action.
        client:
          allOf:
          - $ref: '#/components/schemas/LogEventClient'
          description: The client the action originated from. Omitted for SaaS Manager system events.
        target:
          type: array
          items:
            $ref: '#/components/schemas/LogEventTarget'
          description: The objects the action was performed on. Not all events have targets.
        details:
          description: Detailed information about the event. The shape varies by event type, e.g. field-value changes or counts of objects updated by an integration.
      additionalProperties: false
    Error:
      type: object
      properties:
        type:
          type: string
          description: A URI reference identifying the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem.
        status:
          type: integer
          description: The HTTP status code.
          format: int32
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Validation errors keyed by field name. Present on 400 responses.
        traceId:
          type: string
          description: A trace identifier for correlating the error with SaaS Manager support.
      additionalProperties: false
      description: An error response (RFC 7807 problem details).
    LogEventClient:
      type: object
      properties:
        ipAddress:
          type: string
          description: The IP address from which the event originated.
      additionalProperties: false
    LogEventActor:
      type: object
      properties:
        id:
          type: string
          description: The SaaS Manager ID of the target.
        type:
          type: string
          description: The type of the target, e.g. "User", "CustomerIntegration", "CustomerApp" or "ApiClient".
        displayName:
          type: string
          description: The display name of the target.
        alternateId:
          type: string
          description: An alternate identifier for the target, typically the target's email address.
      additionalProperties: false
    LogEvents:
      type: object
      properties:
        next:
          type: string
          description: 'A cursor URL for the next page of results. Unlike the rest of the SaaS Manager API (which returns no value once paging is complete), the audit log is an append-only stream: this URL always points at where to resume, so keep following it to receive new events as they are written. The same URL is also returned in the `link` response header with `rel="next"`.'
        results:
          type: array
          items:
            $ref: '#/components/schemas/LogEvent'
          description: The audit log events for this page, oldest first (or newest first when sortOrder is DESCENDING).
      additionalProperties: false
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'OAuth 2.0. Obtain an access token via the Client Credentials or Authorization Code flow, then send it as `Authorization: Bearer <token>`.'
      flows:
        clientCredentials:
          tokenUrl: https://app.trelica.com/connect/token
          scopes:
            Apps.Read: Read-only access to applications
            Apps.Users.Read: Read-only access to application accounts
            Apps.Write: Write access to applications
            Assets.Read: Read-only access to devices
            Assets.Write: Write access to devices
            AuditLog.Read: Read-only access to the audit log
            Contracts.Read: Read-only access to contracts
            Contracts.Write: Write access to contracts
            People.Read: Read-only access to people and teams
            People.Write: Write access to people and teams
            Users.Read: Read-only access to users with access to SaaS Manager
            Users.Write: Write access to users with access to SaaS Manager
            Workflows.Read: Read-only access to workflow definitions
            Workflows.Runs.Read: Read-only access to workflow runs
            Workflows.Runs.Execute: Execute workflow run actions
            Workflows.Runs.ReadSecrets: Read workflow run secrets
            offline_access: Issue a refresh token alongside the access token (Authorization Code flow)
        authorizationCode:
          authorizationUrl: https://app.trelica.com/connect/authorize
          tokenUrl: https://app.trelica.com/connect/token
          scopes:
            Apps.Read: Read-only access to applications
            Apps.Users.Read: Read-only access to application accounts
            Apps.Write: Write access to applications
            Assets.Read: Read-only access to devices
            Assets.Write: Write access to devices
            AuditLog.Read: Read-only access to the audit log
            Contracts.Read: Read-only access to contracts
            Contracts.Write: Write access to contracts
            People.Read: Read-only access to people and teams
            People.Write: Write access to people and teams
            Users.Read: Read-only access to users with access to SaaS Manager
            Users.Write: Write access to users with access to SaaS Manager
            Workflows.Read: Read-only access to workflow definitions
            Workflows.Runs.Read: Read-only access to workflow runs
            Workflows.Runs.Execute: Execute workflow run actions
            Workflows.Runs.ReadSecrets: Read workflow run secrets
            offline_access: Issue a refresh token alongside the access token (Authorization Code flow)
    bearerAuth:
      type: http
      description: A bearer access token obtained via OAuth 2.0.
      scheme: bearer
      bearerFormat: JWT
    clientBasicAuth:
      type: http
      description: 'HTTP Basic authentication: the client ID and client secret, joined with a colon and Base64-encoded (RFC 7617).'
      scheme: basic
x-provenance:
  method: harvested
  publisher: 1Password
  source: https://www.1password.dev/openapi/saas_manager_api.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)