1Password Teams API

openapi: 3.2.0
info:
  title: SaaS Manager Teams 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: Teams
  description: List and manage teams and the team hierarchy.
paths:
  /api/people/v1/teams:
    put:
      tags:
      - Teams
      summary: Create or update a team
      description: 'Creates a new team when no ID is supplied (returns 201 with the created team), or updates

        an existing team''s name and/or parent when an ID is supplied (returns 200). A team cannot

        be moved beneath one of its own descendants.


        **Required scope:** `People.Write` (Write access to people and teams)'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamListItem'
            example:
              parentId: 65207c3ffa0d2abb07955315
              id: 65207c3ffa0d2abb07955316
              name: Customer Success
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamListItem'
              example:
                parentId: 65207c3ffa0d2abb07955315
                id: 65207c3ffa0d2abb07955316
                name: Customer Success
        '200':
          description: OK
        '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
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: Not found.
                status: 404
                detail: The requested resource does not exist or you do not have access to it.
                traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - People.Write
      operationId: putApiPeopleV1Teams
      x-operation-id-source: derived
  /api/people/v1/teams/{id}:
    get:
      tags:
      - Teams
      summary: Get a team
      description: 'Fetches a single team by ID, including its parent team ID (if any).


        **Required scope:** `People.Read` (Read-only access to people and teams)'
      parameters:
      - name: id
        in: path
        description: The team's ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamListItem'
              example:
                parentId: 65207c3ffa0d2abb07955315
                id: 65207c3ffa0d2abb07955316
                name: Customer Success
        '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
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: Not found.
                status: 404
                detail: The requested resource does not exist or you do not have access to it.
                traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - People.Read
      operationId: getApiPeopleV1TeamsById
      x-operation-id-source: derived
    delete:
      tags:
      - Teams
      summary: Delete a team
      description: 'Deletes the team with the given ID, along with its descendants, and removes the

        corresponding memberships from people. Teams that are in use by integrations cannot be

        deleted.


        **Required scope:** `People.Write` (Write access to people and teams)'
      parameters:
      - name: id
        in: path
        description: The team's ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '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
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: Not found.
                status: 404
                detail: The requested resource does not exist or you do not have access to it.
                traceId: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - People.Write
      operationId: deleteApiPeopleV1TeamsById
      x-operation-id-source: derived
  /api/people/v1/teams/list:
    get:
      tags:
      - Teams
      summary: List teams
      description: 'Returns all teams as a flat list; each entry carries its parent team ID (if any).


        **Required scope:** `People.Read` (Read-only access to people and teams)'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TeamListItem'
              example:
              - id: 65207c3ffa0d2abb07955307
                name: Engineering
              - parentId: 65207c3ffa0d2abb07955307
                id: 65207c3ffa0d2abb07955309
                name: Development
              - parentId: 65207c3ffa0d2abb07955307
                id: 65207c3ffa0d2abb07955308
                name: DevOps
              - id: 65207c3ffa0d2abb0795530a
                name: Finance
              - parentId: 65207c3ffa0d2abb0795530a
                id: 65207c3ffa0d2abb0795530b
                name: Accounts Payable
              - id: 65207c3ffa0d2abb0795530e
                name: HR
              - id: 65207c3ffa0d2abb07955313
                name: Sales
              - parentId: 65207c3ffa0d2abb07955313
                id: 65207c3ffa0d2abb07955314
                name: Technical Pre-sales
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - People.Read
      operationId: getApiPeopleV1TeamsList
      x-operation-id-source: derived
  /api/people/v1/teams/tree:
    get:
      tags:
      - Teams
      summary: Get the team hierarchy
      description: 'Returns all teams as a nested tree, starting from the root teams.


        **Required scope:** `People.Read` (Read-only access to people and teams)'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TeamTree'
              example:
              - children:
                - id: 65207c3ffa0d2abb07955309
                  name: Development
                - id: 65207c3ffa0d2abb07955308
                  name: DevOps
                id: 65207c3ffa0d2abb07955307
                name: Engineering
              - children:
                - id: 65207c3ffa0d2abb0795530b
                  name: Accounts Payable
                - id: 65207c3ffa0d2abb0795530c
                  name: Accounts Receivable
                - id: 65207c3ffa0d2abb0795530d
                  name: FP&A
                id: 65207c3ffa0d2abb0795530a
                name: Finance
              - id: 65207c3ffa0d2abb0795530e
                name: HR
              - children:
                - id: 65207c3ffa0d2abb07955314
                  name: Technical Pre-sales
                id: 65207c3ffa0d2abb07955313
                name: Sales
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
      - oauth2:
        - People.Read
      operationId: getApiPeopleV1TeamsTree
      x-operation-id-source: derived
components:
  schemas:
    TeamTree:
      type: object
      properties:
        children:
          type: array
          items:
            $ref: '#/components/schemas/TeamTree'
          description: The team's immediate child teams
        id:
          type: string
          description: The team's unique ID. Omit when creating a team by name.
        name:
          type: string
          description: The team's name
      additionalProperties: false
      description: A team and its child teams, nested as a tree
    TeamListItem:
      type: object
      properties:
        parentId:
          type:
          - string
          - 'null'
          description: The ID of the parent team, or null for a root team
        id:
          type:
          - string
          - 'null'
          description: The team's unique ID. Omit when creating a team by name.
        name:
          type:
          - string
          - 'null'
          description: The team's name
      additionalProperties: false
      description: A team together with its parent team ID
    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).
  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)