HERE Secret Management API

openapi: 3.2.0
info:
  title: Authentication API v1.1 Secret Management 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: Secret Management
  description: Secret Management APIs enable authorized identities to securely upload and manage third-party credentials for use in the platform.
paths:
  /secrets:
    parameters:
    - $ref: '#/components/parameters/XCorrelationId'
    - $ref: '#/components/parameters/XRequestId'
    post:
      tags:
      - Secret Management
      summary: Create Secret
      operationId: createSecret
      description: 'Creates a new Secret for use in Platform runtimes.

        The Secret will be enabled on creation.

        A maximum of 5 Secrets are maintained per User or App at any given point.

        A Secret can be used to store third-party credentials for use in Platform runtimes.


        Assigns "read", "manage", "addGrant:read", and "addGrant:manage" rights to the caller.

        The calling User or App can now delegate access to the Secret in more granular fashion,

        using ''read'' or ''manage'' to another identity in its Realm using the grants APIs.

        For secure Production systems, HERE recommends creating a delegate App in your Realm,

        granting only the ''read'' permission to that App via the ''grantReadTo'' query string parameter,

        and using that App as RunAsId in your Platform runtime.


        Access Control:

        * The calling principal must be in a realm of type **"olp"**.

        * The calling principal MUST NOT include a project scope.'
      security:
      - UserOrClientBearerToken: []
      parameters:
      - in: query
        name: grantReadTo
        schema:
          type: string
        required: false
        description: 'HRN of the identity to whom to also grant read access.

          For a secure production system using Application delegates, this is a convenience API that can be used to

          create a Secret and grant read access in one step.

          When used with a delegate App and the RunAsId feature, the target App''s background runtimes will

          receive the decoded secret in a file.


          </br>You can also omit this parameter, and optionally invoke the Grants API at a later time, to achieve

          the same effect.

          '
        example: hrn:here:account::myrealm:app/CUtxqFuI0bprujcvO3h8
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '201':
          description: Created
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        '400':
          description: '* E110100 - Secret cannot be stored based on client input.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: '* E110001 - Unauthorized due to invalid credentials.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '* E110102 - No app exists with the specified HRN.

            * E110106 - No user exists with the specified HRN.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: '* E110002 - Reached allowed maximum number of Secrets per user or app. Delete a Secret to store another one.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '* E110003 - Request blocked because of too many requests made. Wait for a while before making a new request.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      parameters:
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/Limit'
      tags:
      - Secret Management
      summary: List Secrets
      operationId: listSecrets
      description: 'Lists the secrets stored for the calling user or app.


        Access Control:

        * The calling principal must be in a realm of type **"olp"**.

        * The calling principal MUST NOT include a project scope.'
      security:
      - UserOrClientBearerToken: []
      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/SecretPageWToken'
        '401':
          description: '* E110001 - Unauthorized due to invalid credentials.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '* E110003 - Request blocked because of too many requests made. Wait for a while before making a new request.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /secrets/{secret}:
    parameters:
    - $ref: '#/components/parameters/Secret'
    - $ref: '#/components/parameters/XCorrelationId'
    - $ref: '#/components/parameters/XRequestId'
    get:
      tags:
      - Secret Management
      summary: Retrieve Secret
      operationId: getSecret
      description: 'Retrieves the specified Secret.


        Access Control:

        * The calling principal must have **"read"** action permission for the resource **"{secret}"** in the **"account"** service.

        * The calling principal MUST NOT include a project scope.'
      security:
      - UserOrClientBearerToken: []
      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/Secret'
        '401':
          description: '* E110001 - Unauthorized due to invalid credentials.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '* E110103 - The secret does not exist.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '* E110003 - Request blocked because of too many requests made. Wait for a while before making a new request.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - Secret Management
      summary: Update Secret
      operationId: updateSecret
      description: 'Updates a Secret.


        Access Control:

        * The calling principal must have **"manage"** action permission for the resource **"{secret}"** in the **"account"** service.

        * The calling principal MUST NOT include a project scope.'
      security:
      - UserOrClientBearerToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSecretRequest'
      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/Secret'
        '401':
          description: '* E110001 - Unauthorized due to invalid credentials.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '* E110103 - The Secret does not exist.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '* E110003 - Request blocked because of too many requests made. Wait for a while before making a new request.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Secret Management
      summary: Delete Secret
      operationId: deleteSecret
      description: 'Deletes the Secret. This Secret is no longer available for authentication or authorization.


        Since the Secret cannot be recovered once deleted, it is recommended that the caller of this

        end-point should enforce a confirmation of delete action (Example: Confirm box saying: Are you sure you want to

        delete this Secret?).


        Access Control:

        * The calling principal must have **"manage"** action permission for the resource **"{secret}"** in the **"account"** service.

        * The calling principal MUST NOT include a project scope.'
      security:
      - UserOrClientBearerToken: []
      responses:
        '204':
          description: No Content
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          description: '* E110001 - Unauthorized due to invalid credentials.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '* E110103 - The Secret does not exist.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '* E110003 - Request blocked because of too many requests made. Wait for a while before making a new request.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /secrets/{secret}/enable:
    parameters:
    - $ref: '#/components/parameters/Secret'
    - $ref: '#/components/parameters/XCorrelationId'
    - $ref: '#/components/parameters/XRequestId'
    post:
      security:
      - UserOrClientBearerToken: []
      tags:
      - Secret Management
      summary: Enable Secret
      description: 'Enables the Secret.


        Access Control:

        * The calling principal must have **"manage"** action permission for the resource **"{secret}"** in the **"account"** service.

        * The calling principal MUST NOT include a project scope.'
      operationId: enableSecret
      responses:
        '204':
          description: No Content
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          description: '* E110001 - Unauthorized due to invalid credentials.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '* E110103 - The Secret does not exist.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '* E110003 - Request blocked because of too many requests made. Wait for a while before making a new request.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /secrets/{secret}/disable:
    parameters:
    - $ref: '#/components/parameters/Secret'
    - $ref: '#/components/parameters/XCorrelationId'
    - $ref: '#/components/parameters/XRequestId'
    post:
      security:
      - UserOrClientBearerToken: []
      tags:
      - Secret Management
      summary: Disable Secret
      description: 'Disables the Secret.


        Access Control:

        * The calling principal must have **"manage"** action permission for the resource **"{secret}"** in the **"account"** service.

        * The calling principal MUST NOT include a project scope.'
      operationId: disableSecret
      responses:
        '204':
          description: No Content
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          description: '* E110001 - Unauthorized due to invalid credentials.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: '* E110103 - The Secret does not exist.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '* E110003 - Request blocked because of too many requests made. Wait for a while before making a new request.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorDetail:
      type: object
      properties:
        title:
          type: string
          description: Error message
          example: Invalid size value
        source:
          type: string
          description: Reference to JSON path
          example: $.data.attributes[0].size
        message:
          type: string
          description: Detailed error message
          example: Size must be between 3 and 64
        messageTemplate:
          type: string
          description: Optional error template
          example: validation.constraint.between
        messagePlaceholders:
          type: object
          additionalProperties: {}
          example:
            field: size
            min: 3
            max: 64
    CreateSecretRequest:
      type: object
      required:
      - id
      - secret
      - type
      properties:
        id:
          type: string
          description: 'ID for the Secret.  ID must contain 4 and 16 lowercase alphanumeric characters [a-z0-9] plus the hyphen character [-].

            '
          example: my-secret-1
        secret:
          type: string
          description: 'Web-safe-base64-encoded secret file contents.

            This property is redacted from the Retrieve Secret and List Secrets APIs,

            but is securely delivered to Platform Runtimes, as long as the Secret is enabled and not expired.

            The ''sha256'' property in the Retrieve Secret and List Secrets APIs response provides the ability to validate

            the stored value, but since sha-256 is a one-way hash, the underlying ''secret'' remains hidden from view.

            '
          example: bXktc2VjcmV0PWZvby1iYXI=
        type:
          type: string
          enum:
          - aws
          - custom
          description: '"aws" or "custom".  For "aws", the platform will place the file in ~/.aws/<file>.  For "custom", the

            platform will place the file in ~/.here/<file>.

            '
          example: aws
        filename:
          type: string
          pattern: ^[A-Za-z0-9_\-][A-Za-z0-9_\.\-]*$
          description: 'A relative filename for the platform to use to write the secret in plaintext on the filesystem.

            The file will be placed in the directory as specified by the ''type'' property.

            Defaults to "credentials".

            '
          example: credentials
        name:
          type: string
          description: a descriptive name for the secret
          example: my favorite secret
        enabled:
          type: boolean
          description: 'true for enabled, false for disabled.

            An enabled=false (disabled) secret is not delivered to Platform Runtimes.

            '
          example: true
        expires:
          type: string
          description: 'Date-time formatted time this Secret expires.

            A null value or missing property means there is no end time at which the secret expires.

            This property has no effect if enabled=false.

            An expired secret is not delivered to Platform Runtimes.

            '
          example: '2020-12-28T02:24:00.000Z'
    Secret:
      type: object
      properties:
        id:
          type: string
          description: 'ID for the Secret.  ID must contain 4 and 16 lowercase alphanumeric characters [a-z0-9] plus the hyphen character [-].

            '
          example: my-secret-1
        type:
          type: string
          enum:
          - aws
          - custom
          description: '"aws" or "custom".  For "aws", the platform will place the file in ~/.aws/<file>.  For "custom", the

            platform will place the file in ~/.here/<file>.

            '
          example: aws
        filename:
          type: string
          pattern: ^[A-Za-z0-9_\-][A-Za-z0-9_\.\-]*$
          description: 'A relative filename for the platform to use to write the secret in plaintext on the filesystem.

            The file will be placed in the directory as specified by the ''type'' property.

            Defaults to "credentials".

            '
          example: credentials
        name:
          type: string
          description: a descriptive name for the Secret
          example: my favorite secret
        hrn:
          type: string
          description: 'The HRN for the Secret.

            '
          example: hrn:here:account::myrealm:secret/abc-123
        sha256:
          type: string
          description: 'The SHA-256 hash of the ''secret'' input.  (could also do SHA-256 hash of the base64-decoded secret input).

            '
          example: C01DCECC41CA1E27BB0D41B089528D6D15443AF24E710A005BB2372CD107474E
        enabled:
          type: boolean
          description: 'true for enabled, false for disabled.

            An enabled=false (disabled) secret is not delivered to Platform Runtimes.

            '
          example: true
        created:
          type: string
          description: date-time formatted time of creation of this Secret object.
          example: '2020-12-23T02:24:00.000Z'
        modified:
          type: string
          description: date-time formatted time this Secret object was last modified.
          example: '2020-12-23T02:24:00.000Z'
        expires:
          type: string
          description: 'Date-time formatted time this Secret expires.

            A null value or missing property means there is no end time at which the Secret expires.

            This property has no effect if enabled=false.

            An expired secret is not delivered to Platform Runtimes.

            '
          example: '2020-12-28T02:24:00.000Z'
    PageWithToken:
      type: object
      required:
      - limit
      - total
      - items
      properties:
        limit:
          type: integer
          example: 1
          description: number of entries in the response.
        pageToken:
          type: string
          example: KuMvTQrdHVVKuMDDdcIvTQrdci1FWdcIHVVci1FW
          description: The cursor for pagination. Present only if there is an additional page of data to view.
        total:
          type: integer
          example: 1
          description: The number of federations matching the search criteria.
    UpdateSecretRequest:
      type: object
      properties:
        secret:
          type: string
          description: 'Web-safe-base64-encoded secret file contents.

            '
          example: bXktc2VjcmV0PWZvby1iYXI=
        type:
          type: string
          enum:
          - aws
          - custom
          description: '"aws" or "custom".  For "aws", the platform will place the file in ~/.aws/<file>.  For "custom", the platform will place the file in ~/.here/<file>.

            '
          example: aws
        filename:
          type: string
          pattern: ^[A-Za-z0-9_\-][A-Za-z0-9_\.\-]*$
          description: 'A relative filename for the platform to use to write the secret in plaintext on the filesystem.

            The file will be placed in the directory as specified by the ''type'' property.

            Defaults to "credentials".

            '
          example: credentials
        name:
          type: string
          description: a descriptive name for the secret
          example: my favorite secret
        enabled:
          type: boolean
          description: 'true for enabled, false for disabled.

            An enabled=false (disabled) secret is not delivered to Platform Runtimes.

            '
          example: true
        expires:
          type: string
          description: 'Date-time formatted time this Secret expires.

            A null value or missing property means there is no end time at which the Secret expires.

            This property has no effect if enabled=false.

            An expired secret is not delivered to Platform Runtimes.

            '
          example: '2020-12-28T02:24:00.000Z'
    SecretPageWToken:
      allOf:
      - $ref: '#/components/schemas/PageWithToken'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/Secret'
        example:
          total: 2
          pageToken: 7afd7f8e94eb4844ba45
          limit: 1
          items:
          - id: my-cred-1
            type: aws
            filename: credentials
            name: my favorite secret
            hrn: hrn:here:account::myrealm:secret/abc-123
            sha256: C01DCECC41CA1E27BB0D41B089528D6D15443AF24E710A005BB2372CD107474E
            enabled: true
            created: '2020-12-23T02:24:00.000Z'
            modified: '2020-12-23T02:24:00.000Z'
    ErrorResponse:
      type: object
      required:
      - title
      - status
      - code
      - cause
      - action
      - errorId
      properties:
        title:
          description: Error title
          type: string
          example: Input data failed validation
        errorId:
          type: string
          example: ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1
          description: Unique id for the error. This is searchable from HERE Account logs.
        status:
          description: HTTP Status Code
          type: integer
          example: 400
        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, for future use
          type: string
          example: 4199533b-6290-41db-8d79-edf4f4019a74
        details:
          type: array
          description: Collection of error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
  headers:
    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.
    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.
  parameters:
    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.

        '
    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
    Secret:
      in: path
      required: true
      name: secret
      schema:
        type: string
      description: 'HRN for a Secret.

        '
      example: hrn:here:account::myrealm:secret/abc-123
    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
  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