1Password Authentication API

openapi: 3.2.0
info:
  title: SaaS Manager Authentication 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: Authentication
  description: Obtain an OAuth 2.0 access token. Use the Client Credentials flow for machine-to-machine access, or the Authorization Code flow to act on behalf of a user.
paths:
  /connect/token:
    post:
      tags:
      - Authentication
      summary: Request an access token
      description: 'Exchanges client credentials (or an authorization code / refresh token) for an access token. The client ID and secret are sent via HTTP Basic authentication. The body is `application/x-www-form-urlencoded`.


        - **Client Credentials:** `grant_type=client_credentials` (optional `scope`).

        - **Authorization Code:** `grant_type=authorization_code` with `code` and `redirect_uri`.

        - **Refresh:** `grant_type=refresh_token` with `refresh_token` (requires the `offline_access` scope).'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
              - grant_type
              type: object
              properties:
                grant_type:
                  enum:
                  - client_credentials
                  - authorization_code
                  - refresh_token
                  type: string
                  description: The OAuth 2.0 grant type.
                scope:
                  type: string
                  description: Space-separated scopes to request. Defaults to all scopes configured for the app.
                code:
                  type: string
                  description: The authorization code (Authorization Code flow).
                redirect_uri:
                  type: string
                  description: Must match the redirect URI from the authorization request (Authorization Code flow).
                refresh_token:
                  type: string
                  description: The refresh token (Refresh flow).
        required: true
      responses:
        '200':
          description: The access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              example:
                access_token: eyJhbGciOiJSUzI1NiIsImtpZCI6...
                token_type: Bearer
                expires_in: 3600
                scope: Users.Read offline_access
                refresh_token: 8xLOxBtZp8...
        '400':
          description: The request was invalid (e.g. `invalid_client`, `invalid_scope`, `invalid_grant`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The OAuth 2.0 error code.
                  error_description:
                    type: string
                    description: A human-readable description of the error.
              example:
                error: invalid_client
      security:
      - clientBasicAuth: []
      operationId: postConnectToken
      x-operation-id-source: derived
  /connect/authorize:
    get:
      tags:
      - Authentication
      summary: Authorize (Authorization Code flow)
      description: Redirects the user to the SaaS Manager consent screen. After the user consents, the browser is redirected back to `redirect_uri` with a `code` (and `state`) query parameter, which you then exchange for a token at `/connect/token`. This is a browser-redirect endpoint, not a JSON API call.
      parameters:
      - name: response_type
        in: query
        description: Must be `code`.
        required: true
        schema:
          type: string
      - name: client_id
        in: query
        description: The app's client ID.
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        description: The URL to redirect back to; must match a redirect URI configured on the app.
        required: true
        schema:
          type: string
      - name: scope
        in: query
        description: Space-separated scopes to request.
        required: true
        schema:
          type: string
      - name: state
        in: query
        description: An opaque value echoed back on the redirect; use it to maintain state and prevent CSRF.
        schema:
          type: string
      - name: prompt
        in: query
        description: Force `login` (re-authenticate) or `consent` (re-consent).
        schema:
          type: string
      responses:
        '302':
          description: Redirect to `redirect_uri` with the authorization `code` and `state`.
      operationId: getConnectAuthorize
      x-operation-id-source: derived
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: The access token to send as a bearer token on API requests.
        token_type:
          type: string
          description: The token type; always `Bearer`.
        expires_in:
          type: integer
          description: The token lifetime in seconds (access tokens expire after ~60 minutes).
          format: int32
        scope:
          type: string
          description: The space-separated scopes granted.
        refresh_token:
          type: string
          description: A refresh token (Authorization Code flow only, when `offline_access` was requested).
  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)