openapi: 3.1.0
info:
  title: Trelica REST API
  description: >-
    The Trelica REST API provides programmatic access to the core areas of the
    Trelica SaaS management platform, including applications, people, contracts,
    workflows, assets, audit logs, and user management via SCIM. The API uses
    OAuth 2.0 with either Client Credentials (for integrations) or Authorization
    Code flow (for third-party developer apps). Trelica is now part of
    1Password SaaS Manager.
  version: 1.0.0
  contact:
    name: Trelica Support
    url: https://help.trelica.com/hc/en-us
  license:
    name: Proprietary
  termsOfService: https://www.trelica.com/terms
servers:
  - url: https://app.trelica.com/api
    description: Production (US)
  - url: https://eu.trelica.com/api
    description: Production (EU)
tags:
  - name: Applications
    description: Manage and query SaaS applications in the Trelica catalog
  - name: Application Users
    description: Manage users associated with specific applications
  - name: People
    description: Manage people/employees within the organization
  - name: Contracts
    description: Manage software contracts and renewals
  - name: Workflows
    description: Manage automation workflows
  - name: Assets
    description: Manage software and hardware assets
  - name: Audit Log
    description: Access audit trail of changes and events
  - name: Users (SCIM)
    description: User provisioning via SCIM 2.0 protocol
security:
  - OAuth2ClientCredentials: []
  - OAuth2AuthorizationCode: []
paths:
  /apps/v1:
    get:
      operationId: listApplications
      summary: List Applications
      description: Returns a paginated list of SaaS applications tracked in Trelica.
      tags:
        - Applications
      parameters:
        - name: q
          in: query
          description: Free-text search across application name and description
          schema:
            type: string
        - name: since
          in: query
          description: Filter applications modified after this date/time (ISO 8601)
          schema:
            type: string
            format: date-time
        - name: after
          in: query
          description: Pagination cursor for next page of results
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return (default 100)
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successful response with list of applications
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    description: Pagination URL for next page
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
        '401':
          description: Unauthorized - missing or invalid OAuth token
        '403':
          description: Forbidden - insufficient scope
      security:
        - OAuth2ClientCredentials:
            - Apps.Read
  /apps/v1/{appId}:
    get:
      operationId: getApplication
      summary: Get Application
      description: Returns details for a specific application by its ID.
      tags:
        - Applications
      parameters:
        - name: appId
          in: path
          required: true
          description: Unique identifier for the application
          schema:
            type: string
      responses:
        '200':
          description: Application details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '404':
          description: Application not found
      security:
        - OAuth2ClientCredentials:
            - Apps.Read
  /apps/v1/{appId}/users:
    get:
      operationId: listApplicationUsers
      summary: List Application Users
      description: Returns a paginated list of users associated with a specific application.
      tags:
        - Application Users
      parameters:
        - name: appId
          in: path
          required: true
          description: Unique identifier for the application
          schema:
            type: string
        - name: q
          in: query
          description: Free-text search across user ID, email, and name
          schema:
            type: string
        - name: since
          in: query
          description: Filter users modified after this date/time
          schema:
            type: string
            format: date-time
        - name: after
          in: query
          description: Pagination cursor for next page of results
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return (default 100)
          schema:
            type: integer
            default: 100
        - name: filter
          in: query
          description: SCIM-style filter expression
          schema:
            type: string
      responses:
        '200':
          description: List of application users
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    description: Pagination URL for next page
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppUser'
        '401':
          description: Unauthorized
        '404':
          description: Application not found
      security:
        - OAuth2ClientCredentials:
            - Apps.Users.Read
  /people/v1:
    get:
      operationId: listPeople
      summary: List People
      description: Returns a paginated list of people (employees) in the organization.
      tags:
        - People
      parameters:
        - name: q
          in: query
          description: Free-text search across name and email
          schema:
            type: string
        - name: since
          in: query
          description: Filter people modified after this date/time
          schema:
            type: string
            format: date-time
        - name: after
          in: query
          description: Pagination cursor
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results (default 100)
          schema:
            type: integer
            default: 100
        - name: filter
          in: query
          description: SCIM-style filter expression
          schema:
            type: string
      responses:
        '200':
          description: List of people
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Person'
        '401':
          description: Unauthorized
      security:
        - OAuth2ClientCredentials:
            - People.Read
    post:
      operationId: createPerson
      summary: Create Person
      description: Creates a new person record in Trelica.
      tags:
        - People
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonInput'
      responses:
        '201':
          description: Person created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Invalid request body
        '401':
          description: Unauthorized
      security:
        - OAuth2ClientCredentials:
            - People.Write
  /people/v1/{personId}:
    get:
      operationId: getPerson
      summary: Get Person
      description: Returns details for a specific person by their ID.
      tags:
        - People
      parameters:
        - name: personId
          in: path
          required: true
          description: Unique identifier for the person
          schema:
            type: string
      responses:
        '200':
          description: Person details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '404':
          description: Person not found
      security:
        - OAuth2ClientCredentials:
            - People.Read
    patch:
      operationId: updatePerson
      summary: Update Person
      description: Updates specific fields on a person record.
      tags:
        - People
      parameters:
        - name: personId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonInput'
      responses:
        '200':
          description: Person updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Invalid request body
        '404':
          description: Person not found
      security:
        - OAuth2ClientCredentials:
            - People.Write
  /contracts/v1:
    get:
      operationId: listContracts
      summary: List Contracts
      description: Returns a paginated list of software contracts managed in Trelica.
      tags:
        - Contracts
      parameters:
        - name: q
          in: query
          description: Free-text search across contract name and vendor
          schema:
            type: string
        - name: since
          in: query
          description: Filter contracts modified after this date/time
          schema:
            type: string
            format: date-time
        - name: after
          in: query
          description: Pagination cursor
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results (default 100)
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: List of contracts
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract'
        '401':
          description: Unauthorized
      security:
        - OAuth2ClientCredentials:
            - Contracts.Read
  /contracts/v1/{contractId}:
    get:
      operationId: getContract
      summary: Get Contract
      description: Returns details for a specific contract by its ID.
      tags:
        - Contracts
      parameters:
        - name: contractId
          in: path
          required: true
          description: Unique identifier for the contract
          schema:
            type: string
      responses:
        '200':
          description: Contract details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '404':
          description: Contract not found
      security:
        - OAuth2ClientCredentials:
            - Contracts.Read
  /workflows/v1:
    get:
      operationId: listWorkflows
      summary: List Workflows
      description: Returns a paginated list of automation workflows configured in Trelica.
      tags:
        - Workflows
      parameters:
        - name: q
          in: query
          description: Free-text search across workflow names
          schema:
            type: string
        - name: after
          in: query
          description: Pagination cursor
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results (default 100)
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: List of workflows
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          description: Unauthorized
      security:
        - OAuth2ClientCredentials:
            - Workflows.Read
  /assets/v1:
    get:
      operationId: listAssets
      summary: List Assets
      description: Returns a paginated list of software and hardware assets tracked in Trelica.
      tags:
        - Assets
      parameters:
        - name: q
          in: query
          description: Free-text search across asset names
          schema:
            type: string
        - name: since
          in: query
          description: Filter assets modified after this date/time
          schema:
            type: string
            format: date-time
        - name: after
          in: query
          description: Pagination cursor
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results (default 100)
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: List of assets
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
        '401':
          description: Unauthorized
      security:
        - OAuth2ClientCredentials:
            - Assets.Read
  /audit/v1:
    get:
      operationId: listAuditLogs
      summary: List Audit Logs
      description: Returns a paginated list of audit log entries for all changes and events in Trelica.
      tags:
        - Audit Log
      parameters:
        - name: since
          in: query
          description: Return entries after this date/time
          schema:
            type: string
            format: date-time
        - name: after
          in: query
          description: Pagination cursor
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results (default 100)
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: List of audit log entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditEntry'
        '401':
          description: Unauthorized
      security:
        - OAuth2ClientCredentials:
            - AuditLog.Read
  /scim/v2/Users:
    get:
      operationId: listScimUsers
      summary: List Users (SCIM)
      description: >-
        Returns a list of users using the SCIM 2.0 protocol. Note that SCIM
        endpoints use a different pagination scheme from other Trelica endpoints.
      tags:
        - Users (SCIM)
      parameters:
        - name: startIndex
          in: query
          description: 1-based start index for results (default 1)
          schema:
            type: integer
            default: 1
        - name: count
          in: query
          description: Maximum number of results (default 100)
          schema:
            type: integer
            default: 100
        - name: filter
          in: query
          description: SCIM-style filter expression
          schema:
            type: string
      responses:
        '200':
          description: SCIM list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimListResponse'
        '401':
          description: Unauthorized
      security:
        - OAuth2ClientCredentials:
            - Users.Read
components:
  schemas:
    Application:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the application
        name:
          type: string
          description: Name of the SaaS application
        description:
          type: string
          description: Application description
        category:
          type: string
          description: Application category (e.g., Productivity, Security, HR)
        status:
          type: string
          enum: [Active, Inactive, Discovered, Managed]
          description: Current status of the application
        vendorUrl:
          type: string
          format: uri
          description: Vendor website URL
        userCount:
          type: integer
          description: Number of active users
        annualCost:
          type: number
          description: Annual cost in base currency
        lastModifiedDtm:
          type: string
          format: date-time
          description: Last modification timestamp
    AppUser:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the user in this application
        name:
          type: string
          description: Display name of the user
        email:
          type: string
          format: email
          description: Email address
        status:
          type: string
          enum: [Active, Inactive, Invited, Suspended, Unknown]
          description: User status in this application
        lastLoginDtm:
          type: string
          format: date-time
          description: Last login timestamp
        deleted:
          type: boolean
          description: Whether the user has been deleted
        lastModifiedDtm:
          type: string
          format: date-time
          description: Last modification timestamp
    Person:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the person
        displayName:
          type: string
          description: Full display name
        email:
          type: string
          format: email
          description: Primary email address
        department:
          type: string
          description: Department or team
        jobTitle:
          type: string
          description: Job title
        manager:
          type: string
          description: Manager's person ID
        active:
          type: boolean
          description: Whether the person is currently active
        startDate:
          type: string
          format: date
          description: Employment start date
        endDate:
          type: string
          format: date
          description: Employment end date (if applicable)
        lastModifiedDtm:
          type: string
          format: date-time
          description: Last modification timestamp
    PersonInput:
      type: object
      properties:
        displayName:
          type: string
          description: Full display name
        email:
          type: string
          format: email
          description: Primary email address
        department:
          type: string
          description: Department or team
        jobTitle:
          type: string
          description: Job title
        active:
          type: boolean
          description: Whether the person is active
    Contract:
      type: object
      properties:
        id:
          type: string
          description: Unique contract identifier
        name:
          type: string
          description: Contract name
        vendor:
          type: string
          description: Vendor or supplier name
        applicationId:
          type: string
          description: Associated application ID
        startDate:
          type: string
          format: date
          description: Contract start date
        endDate:
          type: string
          format: date
          description: Contract end date/renewal date
        annualValue:
          type: number
          description: Annual contract value
        currency:
          type: string
          description: Currency code (e.g., USD, GBP)
        status:
          type: string
          enum: [Active, Expired, Pending, Cancelled]
          description: Contract status
        lastModifiedDtm:
          type: string
          format: date-time
          description: Last modification timestamp
    Workflow:
      type: object
      properties:
        id:
          type: string
          description: Unique workflow identifier
        name:
          type: string
          description: Workflow name
        description:
          type: string
          description: Workflow description
        trigger:
          type: string
          description: What triggers this workflow
        status:
          type: string
          enum: [Active, Inactive, Draft]
          description: Workflow status
        lastModifiedDtm:
          type: string
          format: date-time
          description: Last modification timestamp
    Asset:
      type: object
      properties:
        id:
          type: string
          description: Unique asset identifier
        name:
          type: string
          description: Asset name
        type:
          type: string
          enum: [Software, Hardware]
          description: Asset type
        assignedTo:
          type: string
          description: Person ID this asset is assigned to
        status:
          type: string
          enum: [Active, Retired, Unassigned]
          description: Asset status
        lastModifiedDtm:
          type: string
          format: date-time
          description: Last modification timestamp
    AuditEntry:
      type: object
      properties:
        id:
          type: string
          description: Unique audit entry identifier
        timestamp:
          type: string
          format: date-time
          description: When the event occurred
        actorId:
          type: string
          description: ID of the user who performed the action
        actorName:
          type: string
          description: Name of the user who performed the action
        action:
          type: string
          description: The action that was performed
        resourceType:
          type: string
          description: Type of resource affected (Application, Person, Contract, etc.)
        resourceId:
          type: string
          description: ID of the affected resource
        changes:
          type: object
          description: Details of what changed
    ScimListResponse:
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
          description: Total number of matching users
        itemsPerPage:
          type: integer
          description: Number of items in this response
        startIndex:
          type: integer
          description: 1-based index of first result
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ScimUser'
    ScimUser:
      type: object
      properties:
        id:
          type: string
          description: Unique SCIM user identifier
        userName:
          type: string
          description: Username (usually email)
        displayName:
          type: string
          description: Full display name
        active:
          type: boolean
          description: Whether the user is active
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              primary:
                type: boolean
        phoneNumbers:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
        roles:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
        meta:
          type: object
          properties:
            lastModified:
              type: string
              format: date-time
            created:
              type: string
              format: date-time
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for server-to-server integrations
      flows:
        clientCredentials:
          tokenUrl: https://app.trelica.com/connect/token
          scopes:
            Apps.Read: Read application data
            Apps.Users.Read: Read application user data
            People.Read: Read people data
            People.Write: Create and update people records
            Contracts.Read: Read contract data
            Workflows.Read: Read workflow data
            Assets.Read: Read asset data
            AuditLog.Read: Read audit log entries
            Users.Read: Read users via SCIM
    OAuth2AuthorizationCode:
      type: oauth2
      description: OAuth 2.0 Authorization Code flow for third-party developer apps
      flows:
        authorizationCode:
          authorizationUrl: https://app.trelica.com/connect/authorize
          tokenUrl: https://app.trelica.com/connect/token
          scopes:
            Apps.Read: Read application data
            Apps.Users.Read: Read application user data
            People.Read: Read people data
            People.Write: Create and update people records
            Contracts.Read: Read contract data
            Workflows.Read: Read workflow data
            Assets.Read: Read asset data
            AuditLog.Read: Read audit log entries
            Users.Read: Read users via SCIM