openapi: 3.2.0 info: title: Authentication API v1.1 Manage Device Accounts API version: 1.1.x description: 'This specification describes the Authentication v1.1 APIs. NOTE: Swagger UI automatically URL encodes parameters when required. If/when the APIs are called elsewhere make sure to URL encode the parameters when required.' servers: - url: Use API Lookup for a base URL tags: - name: Manage Device Accounts description: APIs to Manage Device Accounts. paths: /devices: parameters: - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/XCorrelationId' get: parameters: - $ref: '#/components/parameters/RealmQuery' - $ref: '#/components/parameters/IdentityProviderQuery' - $ref: '#/components/parameters/ExternalId' - $ref: '#/components/parameters/PageToken' - $ref: '#/components/parameters/Limit' tags: - Manage Device Accounts summary: List Devices operationId: listDevices description: 'List Devices. Access Control: * The calling principal must have **"readDevices"** action permission for the resource **"{realm}"** in the **"account"** service. The *realm* is either taken from the query string parameters, or if absent defaults to the *realm* in the request access token. * The calling principal MUST NOT include a project scope.' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/DeviceList' example: count: 1 items: - id: DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 hrn: hrn:here:account::org123456789:devices/DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 realm: hrn:here:account::org123456789:realm/org123456789 project: hrn:here:account::org123456789:project/my-project-0000 identityProvider: hrn:here:account::org123456789:identityProviders/example-op externalId: vtWk4eNAlYLi2UHJGNONTAM5Q7WV4nxHTZGiyfgpFbQ= enabled: true '400': description: 'Bad Request. * E110000 - Missing required field, etc. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '401': description: 'Missing Authorization header. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '403': description: 'An error has occurred. * E110000 - Subject does not have the required "readDevices" access to the Realm. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '404': description: 'An error has occurred. * E110000 - The requested Realm, or Device with specified Provider and ExternalId, does not exist. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' security: - Bearer: [] delete: parameters: - $ref: '#/components/parameters/RequiredIdentityProvider' - $ref: '#/components/parameters/RequiredExternalId' tags: - Manage Device Accounts summary: Delete Devices operationId: deleteDevices description: 'Delete a Device by its Identity Provider and ExternalId. Deleting multiple Devices at a time is not currently supported. Access Control: * The calling principal must have **"manageDevices"** action permission for the resource **"{realm}"** in the **"account"** service. The *realm* is realm of the device. * The calling principal MUST NOT include a project scope.' responses: '204': description: No Content headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '400': description: 'Bad Request. * E110000 - Missing required field, etc. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '401': description: 'Missing Authorization header. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '403': description: 'An error has occurred. * E110000 - Subject does not have the required "readDevices" access to the Realm. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '404': description: "An error has occurred.\n* E110000 - The requested Identity Provider, or Device with specified Identity Provider and ExternalId, \n does not exist.\n" content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' security: - Bearer: [] /devices/{device}: parameters: - $ref: '#/components/parameters/Device' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/XCorrelationId' get: tags: - Manage Device Accounts summary: Get a Device by HRN operationId: getDevice description: 'Get the Device specified by HRN. Access Control: * The calling principal must have **"readDevices"** action permission for the resource **"{realm}"** in the **"account"** service. The *realm* is identified in the **"{device}"**. * The calling principal MUST NOT include a project scope.' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Device' example: id: DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 hrn: hrn:here:account::org123456789:devices/DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 realm: hrn:here:account::org123456789:realm/org123456789 project: hrn:here:account::org123456789:project/my-project-0000 identityProvider: hrn:here:account::org123456789:identityProviders/example-op externalId: vtWk4eNAlYLi2UHJGNONTAM5Q7WV4nxHTZGiyfgpFbQ= enabled: true '400': description: 'Bad Request. * E110000 - Missing required field, etc. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '401': description: 'Missing Authorization header. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '403': description: 'An error has occurred. * E110000 - Subject does not have the required *"readDevices"* access to the *realm*. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '404': description: 'An error has occurred. * E110000 - The requested Project or Device does not exist. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' security: - Bearer: [] patch: tags: - Manage Device Accounts summary: Update a Device by HRN operationId: updateDevice description: 'Update the Device specified by HRN. Access Control: * The calling principal must have **"manageDevices"** action permission for the resource **"{realm}"** in the **"account"** service. The *realm* is identified in the **"{device}"**. * The calling principal MUST NOT include a project scope.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDevice' example: enabled: true responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Device' example: id: DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 hrn: hrn:here:account::org123456789:devices/DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 realm: hrn:here:account::org123456789:realm/org123456789 project: hrn:here:account::org123456789:project/my-project-0000 identityProvider: hrn:here:account::org123456789:identityProviders/example-op externalId: vtWk4eNAlYLi2UHJGNONTAM5Q7WV4nxHTZGiyfgpFbQ= enabled: true '400': description: 'Bad Request. * E110000 - Missing required field, etc. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '401': description: 'Missing Authorization header. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '403': description: 'An error has occurred. * E110000 - Subject does not have the required *"manageDevices"* access to the *realm*. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '404': description: 'An error has occurred. * E110000 - The requested Project or Device does not exist. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' security: - Bearer: [] delete: tags: - Manage Device Accounts summary: Delete a Device by HRN operationId: deleteDevice description: 'Delete the Device specified by HRN. Access Control: * The calling principal must have **"manageDevices"** action permission for the resource **"{realm}"** in the **"account"** service. The *realm* is identified in the **"{device}"**. * The calling principal MUST NOT include a project scope.' responses: '204': description: No Content headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '400': description: 'Bad Request. * E110000 - Missing required field, etc. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '401': description: 'Missing Authorization header. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '403': description: 'An error has occurred. * E110000 - Subject does not have the required "manageDevices" access to the Realm. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '404': description: 'An error has occurred. * E110000 - The requested Device does not exist. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' security: - Bearer: [] /projects/{project}/devices: get: parameters: - $ref: '#/components/parameters/Project' - $ref: '#/components/parameters/IdentityProviderQuery' - $ref: '#/components/parameters/ExternalId' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/XCorrelationId' - $ref: '#/components/parameters/PageToken' - $ref: '#/components/parameters/Limit' tags: - Manage Device Accounts summary: List Project Devices operationId: listProjectDevices description: 'List Devices in the specified Project. Access Control: * The calling principal must have **"readDevices"** action permission for the resource **"{project}"** in the **"account"** service. * The calling principal MUST NOT include a project scope.' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/DeviceList' example: count: 1 items: - id: DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 hrn: hrn:here:account::org123456789:devices/DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 realm: hrn:here:account::org123456789:realm/org123456789 project: hrn:here:account::org123456789:project/my-project-0000 identityProvider: hrn:here:account::org123456789:identityProviders/example-op externalId: vtWk4eNAlYLi2UHJGNONTAM5Q7WV4nxHTZGiyfgpFbQ= enabled: true '400': description: 'Bad Request. * E110000 - Missing required field, etc. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '401': description: 'Missing Authorization header. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '403': description: 'An error has occurred. * E110000 - Subject does not have the required "readDevices" access to the Realm. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' '404': description: 'An error has occurred. * E110000 - The requested Realm, or Device with specified Provider and ExternalId, does not exist. ' content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/XRequestId' security: - Bearer: [] components: parameters: RequiredIdentityProvider: in: query required: true name: identityProvider schema: type: string description: 'HRN identifying the IdentityProvider. ' example: hrn:here:account::org123456789:identityProvider/example-op Project: in: path required: true name: project schema: type: string description: 'HRN identifying the Project. ' example: hrn:here:authorization::org123456789:project/proj-123456 XCorrelationId: in: header name: X-Correlation-ID schema: type: string required: false description: 'Correlates HTTP requests between a client and server. If not present in the incoming request, it will be generated. This header and value will be included in all loglines including access logs. It will also be propagated to downstream services and returned in the response. ' Limit: in: query name: limit required: false description: Number of records to return. Default is 100 records. Maximum is 100 records. schema: type: integer minimum: 0 maximum: 100 default: 100 RequiredExternalId: in: query required: true name: externalId schema: type: string description: "External identifier for the Device under a third-party Identity Provider. \nIf OpenID Connect Token Exchange was used to create this Device identity, the \nExternalId matches the value of the \"sub\" claim in the OP's access tokens. \nExternal IDs are considered unique for a given an Identity Provider.\n" example: vtWk4eNAlYLi2UHJGNONTAM5Q7WV4nxHTZGiyfgpFbQ= XRequestId: in: header name: X-Request-ID schema: type: string required: false description: 'The unique for the request, used to track this request within the service. X-Request-ID value is NOT propagated to the downstream services. ' PageToken: name: pageToken in: query required: false description: 'If there are more records than ''limit'' (between 1 and 100), and there are multiple pages of records, ''pageToken'' allows for retrieval of individual pages. In order to retrieve subsequent pages, the client should provide the pageToken returned in the result from the previous API call as input to the following API call. Example: If the result for a call to GET /items returns *{..., "pageToken": "abcdefg"}*, in order to retrieve the next page of ''items'' the client should call GET /items?pageToken=abcdefg ' schema: type: string RealmQuery: in: query required: false name: realm schema: type: string description: "HRN identifying the Realm. If neither `identityProvider` nor `realm` is specified, defaults to the realm \nidentified in your access token context.\n" example: hrn:here:account::org123456789:realm/org123456789 IdentityProviderQuery: in: query required: false name: identityProvider schema: type: string description: 'HRN identifying the IdentityProvider. Ignored if `externalId` is not specified in the request. ' example: hrn:here:account::org123456789:identityProvider/example-op Device: in: path required: true name: device schema: type: string description: 'HRN of the Device. ' example: hrn:here:account::org123456789:identityProvider/example-op ExternalId: in: query required: false name: externalId schema: type: string description: "External identifier for the Device under a third-party Identity Provider. \nIf OpenID Connect Token Exchange was used to create this Device identity, the \nExternalId matches the value of the \"sub\" claim in the OP's access tokens. \nExternal IDs are considered unique for a given an Identity Provider. \nIgnored if `identityProvider` is not specified in the request.\n" example: vtWk4eNAlYLi2UHJGNONTAM5Q7WV4nxHTZGiyfgpFbQ= headers: XCorrelationId: schema: type: string required: false description: The X-Correlation-ID for the request, used to track this request in the platform. X-Correlation-ID value is propagated throughout the platform. XRequestId: schema: type: string required: false description: The unique id for the request, used to track this request within the service. X-Request-ID value is NOT propagated to the downstream services. schemas: UpdateDevice: type: object properties: enabled: type: boolean description: true if the Device is enabled for use in the platform, false if disabled for use. example: true ErrorMessage: type: object required: - title - status - code - cause - action - correlationId example: title: Input data failed validation status: 400 code: E110000 cause: The input data in question does not meet validation rules action: Actionable instructions for the user. correlationId: 6c1bce6d-d31f-4275-9d9f-6832d8ba2377 properties: title: type: string description: Title of the error. status: type: integer minimum: 0 maximum: 999 description: HTTP status code of error message. code: type: string description: Identifier for the detailed error code for programmatic error handling. cause: type: string description: The cause of the error. action: type: string description: Actionable instructions for the user. correlationId: type: string description: The Correlation ID for the request for tracking purposes. DeviceList: type: object required: - count - items properties: count: type: integer description: The number of Devices in this page of the List. items: type: array items: $ref: '#/components/schemas/Device' description: List of Devices. pageToken: type: string description: "A pointer to the next page of results, if any. \nNot present if there are no more results after the current page.\n" Device: type: object required: - id - hrn - realm - project properties: id: type: string description: Unique identifier for the Device within the Realm. example: DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 hrn: type: string description: HRN for the Device example: hrn:here:account::org123456789:devices/DEVICE-16835a01-7546-4c1c-9894-5f837f854f83 realm: type: string description: The HRN for the Realm of the Device. example: hrn:here:account::org123456789:realm/org123456789 project: type: string description: The HRN for the Project of the Device. example: hrn:here:account::org123456789:project/my-project-0000 identityProvider: type: string description: "HRN of the IdentityProvider for the Device, if the Device was created from an identity in third-party \nIdentity Provider.\n" example: hrn:here:account::org123456789:identityProviders/example-op externalId: type: string description: "External identifier for the Device under a third-party Identity Provider.\nAn example External ID is a Pseudo-VIN representing a stable hashed VIN identifying \nthe Subject vehicle at the Identity Provider.\nIf OpenID Connect Token Exchange was used to create this Device identity, the\nExternalId matches the value of the \"sub\" claim in the OP's access tokens.\nExternal IDs are considered unique for a given a Identity Provider.\n\nTODO: should we expose this in our APIs, or does it raise Privacy concerns?\n" example: vtWk4eNAlYLi2UHJGNONTAM5Q7WV4nxHTZGiyfgpFbQ= enabled: type: boolean description: true if the Device is enabled for use in the platform, false if disabled for use. example: true securitySchemes: UserOrClientBearerToken: type: http scheme: bearer description: Bearer Token issued to either User or Client. Bearer: type: http scheme: bearer bearerFormat: JWT description: 'A HERE access token obtained from one of the supported OAuth 2.0 authorization flows. For more information on how to get a bearer token, see the [https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html](Identity & Access Management Guide). ' externalDocs: description: The developer guide and related API references are available here. url: https://www.here.com/docs/category/identity-and-access-management