openapi: 3.2.0
info:
  title: Authorization API v1.1 Project Management API
  version: 1.1.0
  description: 'This specification is intended to describe the Authorization v1.1 APIs

    ## Roles

    ### **OrgAdmin** - An entity which has administrative authority over an organization.'
servers:
- url: Use API Lookup for a base URL
security:
- Bearer: []
tags:
- name: Project Management
  description: Project Management
paths:
  /projects:
    post:
      tags:
      - Project Management
      summary: Create the requested Project
      operationId: createProject
      description: 'Create the requested Project in the callers realm


        Access Control:

        * The calling principal must have **"createProject"** action permission in the **"authorization"** service.

        * The calling principal MUST NOT include a project scope.'
      parameters:
      - $ref: '#/components/parameters/XCorrelationId'
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '201':
          description: Created
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      tags:
      - Project Management
      summary: Get the list of all Projects in the Org
      operationId: getAllProjectList
      description: 'Get the list of all Projects in the Organization.


        Access Control:

        * The calling principal must have **"listAllProjects"** action permission in the **"authorization"** service.

        * The calling principal MUST NOT include a project scope.'
      parameters:
      - $ref: '#/components/parameters/realmProjectSearch'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/XCorrelationId'
      security:
      - Bearer: []
      responses:
        '200':
          description: OK
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListWithPageToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /projects/me:
    parameters:
    - $ref: '#/components/parameters/XCorrelationId'
    - $ref: '#/components/parameters/limit'
    - $ref: '#/components/parameters/pageToken'
    - $ref: '#/components/parameters/canManage'
    - $ref: '#/components/parameters/isMember'
    get:
      tags:
      - Project Management
      summary: Get the list of Projects that you are a project admin or a member based on the…
      operationId: getProjectList
      description: 'Get the list of Projects you are a project admin or a member based on the "canManage" or "isMember" parameter''s value.


        **Note:** If neither "canManage" nor "isMember" is specified, "isMember=true" projects are returned. Supported values for "canManage" / "isMember" is : [true]


        Access Control:

        * The calling principal MUST NOT include a project scope.'
      security:
      - Bearer: []
      responses:
        '200':
          description: OK
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectListWithPageToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{project}:
    parameters:
    - $ref: '#/components/parameters/project'
    - $ref: '#/components/parameters/XCorrelationId'
    get:
      tags:
      - Project Management
      summary: Get the requested Project
      operationId: getProject
      description: 'Get the requested Project.


        Access Control:

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

        * The calling principal MUST NOT include a project scope.'
      security:
      - Bearer: []
      responses:
        '200':
          description: OK
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    head:
      tags:
      - Project Management
      summary: Checks the existance of a project in caller realm
      operationId: checkProjectExistance
      description: 'Checks whether a project exists with requested project hrn in caller realm. If project does not exist in the same realm it will return 404.


        Access Control:

        * The calling principal MUST NOT include a project scope.'
      security:
      - Bearer: []
      responses:
        '200':
          description: OK - project exists
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Project Management
      summary: Update the specified Project
      operationId: patchProject
      description: 'Update the specified Project.


        Access Control:

        * The calling principal must have **"write"** action permission for the resource **"{project}"** in the **"authorization"** service.

        * The calling principal MUST NOT include a project scope.'
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProject'
      responses:
        '200':
          description: OK
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Project Management
      summary: Delete the specified Project
      operationId: deleteProject
      description: 'Delete the specified Project.


        Access Control:

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

        * The calling principal MUST NOT include a project scope.'
      security:
      - Bearer: []
      responses:
        '202':
          description: Accepted
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/XCorrelationId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PatchProject:
      type: object
      properties:
        name:
          type: string
          example: My Project
          description: 'The name of the Project

            '
        description:
          type: string
          example: This is my demo Project
          description: 'The description of the Project

            '
    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
    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'
    ProjectRequest:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          example: my-project-0000
          description: 'The id of the Project

            '
        name:
          type: string
          example: My Project
          description: 'The name of the Project

            '
        description:
          type: string
          example: This is my demo Project
          description: 'The description of the Project

            '
    ProjectListWithPageToken:
      type: object
      allOf:
      - $ref: '#/components/schemas/PageWithToken'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/ProjectResponse'
            description: List of Projects.
    PageWithToken:
      type: object
      required:
      - limit
      - total
      - items
      properties:
        limit:
          type: integer
          example: 1
          description: Maximum number of items to return.
        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: Total number of items matching the search criteria.
    ProjectResponse:
      type: object
      properties:
        id:
          type: string
          example: my-project-0000
          description: 'The id of the Project

            '
        hrn:
          type: string
          example: hrn:here:authorization::myrealm:project/my-project-0000
          description: 'The hrn of the Project

            '
        name:
          type: string
          example: My Project
          description: 'The name of the Project

            '
        description:
          type: string
          example: This is my demo Project
          description: 'The description of the Project

            '
  headers:
    XCorrelationId:
      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.

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

        '
    isMember:
      in: query
      name: isMember
      required: false
      description: if true returns all projects of which the caller(user/app) is a member.
      schema:
        type: boolean
    canManage:
      in: query
      name: canManage
      required: false
      description: if true returns all projects of which the caller(user/app) is a project admin.
      schema:
        type: boolean
    pageToken:
      name: pageToken
      in: query
      description: The cursor for pagination. Present only if there is an additional page of data to view.
      schema:
        type: string
      example: KuMvTQrdHVVKuMDDdcIvTQrdci1FWdcIHVVci1FW
    realmProjectSearch:
      in: query
      name: q
      required: false
      description: A free text query string used to filter the results.  A search against projects in the realm will consider the 'id', 'name', 'description', fields of the projects. The precise search algorithm used to match projects is not specified, but generally any projects where one of the considered fields has a full or partial match should be included in the results.
      schema:
        type: string
    project:
      in: path
      name: project
      required: true
      description: HRN identifying the project
      schema:
        type: string
      example: hrn:here:authorization::myrealm:project/my-project-0000
  responses:
    NotFound:
      description: The requested resource was not found, see error response for details
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/XCorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: You do not have permission to perform this action
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/XCorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Access is denied due to invalid credentials
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/XCorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid input provided, see error response for details
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/XCorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer Access Token issued to either the User or Client.
externalDocs:
  description: The developer guide and related API references are available here.
  url: https://www.here.com/docs/category/identity-and-access-management