> ## Documentation Index > Fetch the complete documentation index at: https://www.1password.dev/llms.txt > Use this file to discover all available pages before exploring further. # Update selected details of a device > Partially updates a device: only the fields present in the request body are changed. Omitting a field leaves it untouched, whereas sending an explicit `null` clears it. At least one field must be supplied. **Required scope:** `Assets.Write` (Write access to devices) ## OpenAPI ````yaml /openapi/saas_manager_api.json patch /api/assets/v1/{id} openapi: 3.0.4 info: title: SaaS Manager API description: >- By accessing or using 1Password Developer Tools, you agree to the [API and SDK Terms of Service](https://1password.com/legal/api-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](#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](https://tools.ietf.org/html/rfc3339) 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](https://tools.ietf.org/html/rfc7644#section-3.4.2.2). 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`). | Operator | Meaning | Behaviour | |----------|---------|-----------| | `eq` | equal | Attribute value is identical to the operator value | | `ne` | not equal | Attribute value differs from the operator value | | `co` | contains | Attribute value contains the operator value text | | `sw` | starts with | Attribute value starts with the operator value text | | `ew` | ends with | Attribute value ends with the operator value text | | `pr` | present | Attribute has a non-empty / non-null value | | `gt` | greater than | Attribute value is greater than the operator value | | `ge` | greater than or equal | Attribute value is greater than or equal to the operator value | | `lt` | less than | Attribute value is less than the operator value | | `le` | less than or equal | Attribute value is less than or equal to the operator value | For `gt`/`ge`/`lt`/`le`, strings compare lexicographically, dates chronologically and numbers numerically. Each list endpoint documents the fields you can filter on. **Examples** | Filter | Result | |--------|--------| | `firstName sw "Jan"` | People whose first name starts with "Jan" | | `teams[name eq "Developers"]` | People in the team called Developers | | `not (leavingDate pr)` | People with no leaving date | | `lastModifiedDtm ge "2021-06-01"` | Records modified on or after 1 June 2021 | ## Errors A `400 Bad Request` indicates a problem with your request. The body is a problem-details object: `errors` maps each offending field to its messages, with `title`, `status`, a `type` URL, and an `extensions.traceId` for correlation: ```json { "errors": { "leavingDate": [ "Error converting value \"2020-40-40\" ..." ] }, "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400, "extensions": { "traceId": "00-91e4405b...-00" } } ``` You should not normally see `500 Internal Server Error`. If you do, the body is a generic message — please contact [saasmanager@1password.com](mailto:saasmanager@1password.com) with details of the request so we can investigate. ## Scopes Scopes define what an API app may do. Following security best practice, grant only the scopes you need. Each endpoint documents the scope(s) it requires. | Scope | Description | |-------|-------------| | `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) | 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 security: [] 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. - name: Applications description: >- List, search and manage applications, and list the accounts (users) on an application. - name: People description: List, search and manage the people in your organization. - name: Teams description: List and manage teams and the team hierarchy. - name: Contracts description: List and manage contracts. - name: Devices description: List and manage devices. The endpoints live under `/api/assets`. - name: Workflows description: >- List workflows (with their triggers and steps), list their runs, and fire signals on steps that are waiting for input. - name: Audit log description: >- Read your organization's audit log: a continuous, filterable stream of events. - name: SCIM description: >- Provision and manage users via the SCIM 2.0 protocol (RFC 7644). These endpoints follow the SCIM standard rather than the conventions used by the rest of the SaaS Manager API: they use `startIndex`/`count` paging, return a SCIM `ListResponse` envelope, identify schemas with `urn:` URIs, and exchange `application/scim+json`. The `ResourceTypes` endpoints support SCIM discovery (RFC 7643). paths: /api/assets/v1/{id}: patch: tags: - Devices summary: Update selected details of a device description: >- Partially updates a device: only the fields present in the request body are changed. Omitting a field leaves it untouched, whereas sending an explicit `null` clears it. At least one field must be supplied. **Required scope:** `Assets.Write` (Write access to devices) parameters: - name: id in: path description: The device's SaaS Manager ID. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DevicePatch' example: status: Deployed assignedToEmail: john.doe@example.com locationName: London, UK customFields: user_department: Engineering required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Device' example: id: 646fcb4fb829ba9df2a94471 status: Deployed statusType: Deployed hardwareVendor: Apple Inc. modelName: MacBook Pro (16-inch, 2021) serialNumber: KOGITG04P5 assetTag: A0000002 purchasedDate: '2016-03-06T00:00:00Z' warrantyExpirationDate: '2017-03-06T00:00:00Z' lifespanExpirationDate: '2019-03-06T00:00:00Z' assignedTo: userId: 6a127db661b442c1afdd77611ad99824 name: Joshua Burns email: joshua.burns@example.com assignedToEmail: joshua.burns@example.com netPrice: 1615 netPriceCurrency: USD platform: Mac isEncrypted: false customFields: user_department: Engineering user_ram_gb: 32 user_accessories: - Charger - Dock createdBy: userId: b1fb51a7c13f4cbf832b304348c8270e name: System email: admin@example.com createdDtm: '2023-05-25T20:55:43.048Z' lastModifiedBy: userId: b1fb51a7c13f4cbf832b304348c8270e name: System email: admin@example.com lastModifiedDtm: '2024-05-27T01:03:26.679Z' '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 '401': description: Unauthorized '403': description: Forbidden '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 security: - oauth2: - Assets.Write components: schemas: DevicePatch: type: object properties: status: type: string description: The device's status, e.g. Deployed nullable: true description: type: string description: A description of the device nullable: true assignedToEmail: type: string description: >- Assign the device to a person by email address. Pass null to unassign. nullable: true locationName: type: string description: >- Assign the device to a location by name (a location is found or created). Pass null to clear. nullable: true serialNumber: type: string description: The serial number nullable: true assetTag: type: string description: The asset tag nullable: true purchaseDate: type: string description: (ISO format) The purchase date format: date-time nullable: true disposalDate: type: string description: (ISO format) The disposal date format: date-time nullable: true warrantyExpirationDate: type: string description: (ISO format) The warranty expiration date format: date-time nullable: true lifespanExpirationDate: type: string description: (ISO format) The end of the device's useful life format: date-time nullable: true enrolledDtm: type: string description: (ISO format) The date the device was enrolled format: date-time nullable: true netPrice: type: number description: The net price, in the currency given by netPriceCurrency format: double nullable: true netPriceCurrency: type: string description: The ISO currency code for netPrice nullable: true notes: type: string description: Notes about the device nullable: true isEncrypted: type: boolean description: Whether the device's storage is encrypted nullable: true platform: allOf: - $ref: '#/components/schemas/DevicePlatform' description: The device's operating system platform nullable: true osVersion: type: string description: The operating system version nullable: true customFields: type: object additionalProperties: {} description: Custom field values to set, keyed by the field's lookup key nullable: true deviceName: type: string description: The device name nullable: true id: type: string description: The device's SaaS Manager ID nullable: true readOnly: true externalId: type: string description: >- The device's external ID, sourced from the integration that imported it. nullable: true readOnly: true hardwareVendor: type: string description: The hardware vendor (manufacturer) nullable: true readOnly: true modelName: type: string description: The model name nullable: true readOnly: true assetType: type: string description: The asset type nullable: true readOnly: true lastSyncDtm: type: string description: The timestamp of the device's last sync from an integration. format: date-time nullable: true readOnly: true createdBy: allOf: - $ref: '#/components/schemas/UserInfo' description: The user that created the device record nullable: true readOnly: true createdDtm: type: string description: The timestamp for when the device record was created format: date-time nullable: true readOnly: true lastModifiedBy: allOf: - $ref: '#/components/schemas/UserInfo' description: The user that last modified the device record nullable: true readOnly: true lastModifiedDtm: type: string description: The timestamp for when the device record was last modified format: date-time nullable: true readOnly: true location: allOf: - $ref: '#/components/schemas/DeviceLocation' description: The device's location. To set the location, use locationName. nullable: true readOnly: true additionalProperties: false description: >- Selected device fields to update. Omitted fields are left unchanged; fields set to null are cleared. Device: type: object properties: id: type: string description: The asset's SaaS Manager ID. Supply to replace an existing asset. nullable: true externalId: type: string description: >- The asset's external ID, sourced from the integration that imported it. nullable: true readOnly: true status: type: string description: >- The device's status. This is the status's reference ID; custom statuses are prefixed `user_`. Defaults to New on creation. nullable: true statusType: enum: - New - ReadyToDeploy - Deployed - OutForRepair - Retired type: string description: >- The base status the device's status maps to. Custom statuses always map to one of these. nullable: true readOnly: true hardwareVendor: type: string description: The hardware vendor (manufacturer). Required when creating an asset. nullable: true modelName: type: string description: The model name. Required when creating an asset. nullable: true assetType: type: string description: The asset type, e.g. Laptop nullable: true serialNumber: type: string description: The serial number nullable: true description: type: string description: A description of the asset, sourced from integrations. nullable: true readOnly: true deviceName: type: string description: The device name, sourced from integrations. nullable: true readOnly: true assetTag: type: string description: The asset tag nullable: true purchasedDate: type: string description: (ISO format) The purchase date format: date-time nullable: true disposalDate: type: string description: (ISO format) The disposal date format: date-time nullable: true warrantyExpirationDate: type: string description: (ISO format) The warranty expiration date format: date-time nullable: true lifespanExpirationDate: type: string description: (ISO format) The end of the asset's useful life format: date-time nullable: true notes: type: string description: Notes about the asset nullable: true assignedTo: allOf: - $ref: '#/components/schemas/DeviceAssignee' description: >- The person the asset is assigned to. To set the assignee, use assignedToEmail. nullable: true readOnly: true assignedToEmail: type: string description: >- Assign the asset to a person by email address. Pass null to unassign. nullable: true netPrice: type: number description: The net price, in the currency given by netPriceCurrency format: double nullable: true netPriceCurrency: type: string description: The ISO currency code for netPrice. Defaults to your base currency. nullable: true enrolledDtm: type: string description: (ISO format) The date the asset was enrolled format: date-time nullable: true lastSyncDtm: type: string description: The timestamp of the asset's last sync from an integration. format: date-time nullable: true readOnly: true platform: allOf: - $ref: '#/components/schemas/DevicePlatform' description: The asset's operating system platform nullable: true osVersion: type: string description: The operating system version nullable: true isEncrypted: type: boolean description: Whether the asset's storage is encrypted nullable: true customFields: type: object additionalProperties: {} description: >- Custom field values, keyed by the field's lookup key. Each value is the field's value directly: a string (text/single-select), a number, an ISO-8601 date, an array of strings (multi-select), or a link object ({ href, description }). nullable: true createdBy: allOf: - $ref: '#/components/schemas/UserInfo' description: The user that created the asset record nullable: true readOnly: true createdDtm: type: string description: The timestamp for when the asset record was created format: date-time nullable: true readOnly: true lastModifiedBy: allOf: - $ref: '#/components/schemas/UserInfo' description: The user that last modified the asset record nullable: true readOnly: true lastModifiedDtm: type: string description: The timestamp for when the asset record was last modified format: date-time nullable: true readOnly: true location: allOf: - $ref: '#/components/schemas/DeviceLocation' description: The asset's location. To set the location, use locationName. nullable: true readOnly: true locationName: type: string description: >- Assign the asset to a location by name (a location is found or created). Pass null to clear. nullable: true additionalProperties: false description: An asset (device) 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). DevicePlatform: enum: - Mac - Windows - iOS - Android - ChromeOS - Linux type: string UserInfo: type: object properties: userId: type: string nullable: true name: type: string nullable: true email: type: string nullable: true additionalProperties: false DeviceLocation: type: object properties: id: type: string description: The location's unique ID name: type: string description: The location's name nullable: true countryCode: type: string description: The location's ISO country code nullable: true additionalProperties: false description: A real world location DeviceAssignee: type: object properties: userId: type: string description: The assignee's SaaS Manager person ID nullable: true name: type: string description: The assignee's name nullable: true email: type: string description: The assignee's email address nullable: true additionalProperties: false description: The person an asset is assigned to 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 `. 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) ```` ## Related topics - [Update selected details of a person](/api-reference/people/update-selected-details-of-a-person.md) - [Update selected details of an application](/api-reference/applications/update-selected-details-of-an-application.md) - [Delete a device](/api-reference/devices/delete-a-device.md)