HERE Support Access API

openapi: 3.2.0
info:
  title: Authentication API v1.1 Support Access 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: Support Access
  description: Manage Account Executive support access
paths:
  /support:
    parameters:
    - $ref: '#/components/parameters/XRequestId'
    - $ref: '#/components/parameters/XCorrelationId'
    get:
      security:
      - Bearer: []
      tags:
      - Support Access
      description: 'Get the support access entry that enables AccountExecutive logins for the calling principal''s realm.


        NOTE: This API will return 404 if Account Executive support access is not enabled for the realm.


        Access Control:

        * The calling principal must have **"readAccountExecutives"** permission in the **"account"** service.

        * The calling principal MUST NOT include a project scope.'
      operationId: getSupportAccess
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportAccess'
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'An error has occurred.

            * 404000: Resource not found. Account executive support access not enabled for this realm.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
      summary: Get support access
      x-summary-source: derived
    post:
      security:
      - Bearer: []
      tags:
      - Support Access
      description: 'Register support access for an authorized user or users to enable AccountExecutive logins to the

        calling principal''s realm. The registered authorized user(s) will be allowed to login as Account Executives

        to the realm.

        * If the registered authorized user''s emailAddress is not the wildcard value ''*'', an email notification will be

        sent indicating that the user has been invited as an AccountExecutive to the realm.

        * If the registered authorized user''s emailAddress is the wildcard value ''*'', no email notification will be sent


        **NOTE:** A maximum of 5 individual email addresses and/or a single wildcard entry ''*'' may be registered for

        AccountExecutive access. This API is idempotent and may be called repeatedly with the same request parameters.

        If an already registered email address is provided, a duplicate email notification will be sent.


        **NOTE:** This API will return 404 if Account Executive support access is not enabled for the realm.


        Access Control:

        * The calling principal must have **"manageAccountExecutives"** permission in the **"account"** service.

        * This API is rate limited to a maximum of **6** calls per minute per realm

        * The calling principal MUST NOT include a project scope.'
      operationId: registerSupportAccessUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupportAccessUserRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportAccess'
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '400':
          description: 'An error has occurred.

            * 400201: This field is required.

            * 400202: Value cannot be empty.

            * 400233: Invalid ''expiresAt'' format.

            * 400240: Illegal email.

            * 400390: Value for ''expiresAt'' must be in the future.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'An error has occurred.

            * 404000: Resource not found. Account executive support access not enabled for this realm.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
      summary: Register support access user
      x-summary-source: derived
    delete:
      parameters:
      - $ref: '#/components/parameters/SupportEmail'
      security:
      - Bearer: []
      tags:
      - Support Access
      description: 'Delete the support access entry.

        * Invalidate any existing logins associated with the deleted support entry

        * Delete any AccountExecutive user accounts that have been created in the realm that are associated with the deleted support entry


        **NOTE:** This API will return 404 if Account Executive support access is not enabled for the realm.


        Access Control:

        * The calling principal must have **"manageAccountExecutives"** permission in the **"account"** service.

        * The calling principal MUST NOT include a project scope.'
      operationId: deleteSupportAccess
      responses:
        '204':
          description: No Content
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'An error has occurred.

            * 404000: Resource not found. Account executive support access not enabled for this realm.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
      summary: Delete support access
      x-summary-source: derived
components:
  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.
    WWWAuthenticate:
      schema:
        type: string
      required: true
      description: Must be included If the protected resource request does not include authentication credentials or does not contain an access token that enables access to the protected resource. The value must have at least one challenge and must be followed by a comma separated list having one or more authentication param values. In case of OAuth2.0, the challenge must use the auth-scheme value "Bearer".
    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:
    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.
    Error403Response:
      type: object
      required:
      - title
      - status
      - code
      - cause
      - action
      - correlationId
      properties:
        title:
          description: Error title
          type: string
          example: These credentials do not authorize access for this operation.
        status:
          description: HTTP Status Code
          type: integer
          example: 403
        code:
          description: Service specific error code
          type: string
          example: E202101
        cause:
          description: The cause of the error
          type: string
          example: App/User WgxjTzUL8sTbq5fMDPDg/HERE-f7ef7b16-6deb-4b44-986f-d86deed59980 credentials do not authorize access to perform manage action on hrn:here:authorization::HERE:serviceDescriptor/SERVICE-00000000-0000-0000-0000-000000000000 via SERVICE-00000000-0000-0000-0000-000000000000 because No matching permissions found for the identity, its groups and roles, or the realm.
        action:
          description: Actionable instructions for the API consumer
          type: string
          example: Add/Share the necessary permissions to the identity.
        correlationId:
          description: Trace ID associated with this request.
          type: string
          example: 4199533b-6290-41db-8d79-edf4f4019a74
        errorId:
          type: string
          example: ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1
          description: Unique id for the error. This is searchable from HERE Account logs.
        error:
          type: string
          description: Human-readable error
          example: invalid_request
        error_description:
          type: string
          description: Human-readable error description
          example: 'errorCode: 403403. These credentials do not authorize access for this operation.'
    SupportAccess:
      type: object
      properties:
        hrn:
          type: string
          description: HRN of the registered support access entry
          example: hrn:here:account::rlm12345:support/SUPPORT-c57f1bd6-d4aa-11ed-afa1-0242ac120002
        authorizedUsers:
          type: array
          items:
            type: object
            properties:
              emailAddress:
                type: string
                description: Email address of user authorized for support access in this realm or '*' to represent any @here.com email address.
                example: john.doe@here.com
              expiresAt:
                type: string
                description: Time that this user's access expires
                format: date-time
                example: '2023-01-21T17:32:28Z'
          description: List of users authorized for support access in this realm
          maxItems: 6
    SupportAccessUserRequest:
      type: object
      required:
      - emailAddress
      properties:
        emailAddress:
          type: string
          description: Email address of user being authorized for support access in this realm.  Must end in @here.com or equal '*' to represent any @here.com email address.
          example: john.doe@here.com
        expiresAt:
          type: string
          description: Time that this user's access expires. Must be in yyyy-MM-ddTHH:mm:ss(.NNN)Z format. If omitted, this user's access does not expire.
          format: date-time
          example: '2023-01-21T17:32:28.152Z'
    Error401Response:
      type: object
      required:
      - title
      - status
      - code
      - cause
      - action
      - correlationId
      properties:
        title:
          type: string
          example: ''
          description: ''
        status:
          description: HTTP Status Code
          type: integer
          example: 401
        code:
          description: Service specific error code
          type: string
          example: E202101
        cause:
          description: The cause of the error
          type: string
          example: The input data in question does not meet validation rules
        action:
          description: Actionable instructions for the API consumer
          type: string
          example: Correct input data and retry request
        correlationId:
          description: Trace ID associated with this request.
          type: string
          example: 4199533b-6290-41db-8d79-edf4f4019a74
        errorId:
          type: string
          example: ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1
          description: Unique id for the error. This is searchable from HERE Account logs.
        message:
          description: Authorization error message
          type: string
          example: Unauthorized to perform this operation.
  parameters:
    SupportEmail:
      in: query
      required: false
      name: emailAddress
      schema:
        type: string
      description: 'Email address of the authorizedUser entry to delete.  If omitted, all authorizedUser entries **and** the entire

        authorizedUsers list itself will be deleted.  The authorizedUsers list will not appear in subsequent GET calls

        until a new authorizedUser entry is added back.

        '
    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.

        '
    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.

        '
  responses:
    Forbidden:
      description: You do not have permission to perform this action
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/XCorrelationId'
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error403Response'
    Unauthorized:
      description: Access is denied due to invalid credentials
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/XCorrelationId'
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
        WWW-Authenticate:
          $ref: '#/components/headers/WWWAuthenticate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error401Response'
  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