openapi: 3.2.0
info:
  description: '# Authentication

    The Chef Automate API typically uses an API token passed in the header of your API request.'
  title: Chef Automate API Documentation Projects API
  termsOfService: https://www.chef.io/terms-and-conditions-of-use/
  contact:
    url: https://www.chef.io/support/
    email: support@chef.io
  license:
    name: Apache 2.0
    url: https://github.com/chef/automate/blob/main/LICENSE
  version: version not set
  x-logo:
    altText: Chef logo
    url: /images/chef-automate-logo.svg
servers:
- url: https://automate.chef.io
tags:
- description: Projects are used to group and permission Chef Automate resources as well as ingested data, specifically Compliance reports, Chef Infra Server events, and Infrastructure nodes.
  name: Projects
  x-displayName: IAM Projects
paths:
  /apis/iam/v2/projects:
    get:
      description: 'Lists all projects.


        Authorization Action:

        ```

        iam:projects:list

        ```'
      tags:
      - Projects
      summary: Lists all projects
      operationId: Policies_ListProjects
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.iam.v2.ListProjectsResp'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
    post:
      description: 'Creates a new project to be used in the policies that control permissions in Automate.


        A project defines the scope of resources in a policy statement. Resources can be in more than one project.


        When a project is created, the system also creates three policies associated with the new project,

        one for each of the following roles: editor, viewer, and project owner.

        You can optionally pass the `skip_policies` flag set to `true` to skip the creation of these policies.


        Authorization Action:

        ```

        iam:projects:create

        ```'
      tags:
      - Projects
      summary: Creates a project
      operationId: Policies_CreateProject
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.iam.v2.CreateProjectResp'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      x-code-samples:
      - lang: JSON
        source: '{"name": "My Custom Project", "id": "custom-project", "skip_policies": true}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.iam.v2.CreateProjectReq'
        required: true
  /apis/iam/v2/projects/{id}:
    get:
      description: 'Returns the details for a project.


        Authorization Action:

        ```

        iam:projects:get

        ```'
      tags:
      - Projects
      summary: Gets a project
      operationId: Policies_GetProject
      parameters:
      - description: ID of the project.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.iam.v2.GetProjectResp'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
    put:
      description: 'Updates the name of an existing project.


        Authorization Action:

        ```

        iam:projects:update

        ```'
      tags:
      - Projects
      summary: Updates a project
      operationId: Policies_UpdateProject
      parameters:
      - description: Unique ID. Cannot be changed.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.iam.v2.UpdateProjectResp'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      x-code-samples:
      - lang: JSON
        source: '{"name": "My Custom Updated Project Name"}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.iam.v2.UpdateProjectReq'
        required: true
    delete:
      description: 'Deletes a project from any resources tagged with it.


        Also deletes this project from any project list in any policy statements.

        If the resulting project list for a given statement is empty, it is deleted.

        If the resulting policy has no statements, it is also deleted.


        Authorization Action:

        ```

        iam:projects:delete

        ```'
      tags:
      - Projects
      summary: Deletes a project
      operationId: Policies_DeleteProject
      parameters:
      - description: ID of the project.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.iam.v2.DeleteProjectResp'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
components:
  schemas:
    google.protobuf.Any:
      type: object
      properties:
        type_url:
          type: string
        value:
          type: string
          format: byte
    chef.automate.api.iam.v2.DeleteProjectResp:
      type: object
      example:
        id: custom-project
        name: My Custom Project
    chef.automate.api.iam.v2.ProjectRulesStatus:
      type: string
      default: PROJECT_RULES_STATUS_UNSET
      enum:
      - PROJECT_RULES_STATUS_UNSET
      - RULES_APPLIED
      - EDITS_PENDING
      - NO_RULES
    chef.automate.api.iam.v2.Project:
      type: object
      properties:
        id:
          description: Unique ID. Cannot be changed.
          type: string
        name:
          description: Name for the project.
          type: string
        status:
          description: The current status of the rules for this project.
          $ref: '#/components/schemas/chef.automate.api.iam.v2.ProjectRulesStatus'
        type:
          description: Whether this policy is user created (`CUSTOM`) or chef managed (`CHEF_MANAGED`).
          $ref: '#/components/schemas/chef.automate.api.iam.v2.Type'
    chef.automate.api.iam.v2.CreateProjectResp:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/chef.automate.api.iam.v2.Project'
      example:
        id: custom-project
        name: My Custom Project
    chef.automate.api.iam.v2.ListProjectsResp:
      type: object
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.iam.v2.Project'
      example:
        projects:
        - id: custom-project
          name: My Custom Project
        - id: custom-project-2
          name: My Custom Project 2
    chef.automate.api.iam.v2.UpdateProjectReq:
      type: object
      required:
      - id
      - name
      properties:
        id:
          description: Unique ID. Cannot be changed.
          type: string
        name:
          description: Name for the project.
          type: string
      example:
        name: My Custom Project
    chef.automate.api.iam.v2.CreateProjectReq:
      type: object
      required:
      - id
      - name
      properties:
        id:
          description: Unique ID. Cannot be changed.
          type: string
        name:
          description: Name for the new project.
          type: string
        skip_policies:
          description: Boolean flag to skip adding policies associated with the project. Set to false by default.
          type: boolean
      example:
        id: custom-project
        name: My Custom Project
        skip_policies: true
    grpc.gateway.runtime.Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
        error:
          type: string
        message:
          type: string
    chef.automate.api.iam.v2.Type:
      type: string
      default: CHEF_MANAGED
      enum:
      - CHEF_MANAGED
      - CUSTOM
    chef.automate.api.iam.v2.UpdateProjectResp:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/chef.automate.api.iam.v2.Project'
      example:
        id: custom-project
        name: My Custom Project
    chef.automate.api.iam.v2.GetProjectResp:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/chef.automate.api.iam.v2.Project'
      example:
        id: custom-project
        name: My Custom Project
  securitySchemes:
    APIToken:
      description: Authenticate with the Automate API using an API Token.
      type: apiKey
      name: api-token
      in: header
x-tagGroups:
- name: Compliance
  tags:
  - ReportingService
  - StatsService
  - JobsService
  - ProfilesService
  - Comp_Assets
- name: Report Manager
  tags:
  - ReportManagerService
- name: Infra
  tags:
  - ConfigMgmt
  - InfraProxy
- name: Ingest
  tags:
  - ChefIngester
  - JobScheduler
- name: Node Management
  tags:
  - NodeManagerService
  - NodesService
- name: Event Feed
  tags:
  - EventFeedService
- name: Secrets
  tags:
  - SecretsService
- name: Applications
  tags:
  - service_groups
  - retention
  - ApplicationsService
- name: Data Feed
  tags:
  - DatafeedService
- name: Data Lifecycle
  tags:
  - DataLifecycle
- name: Notifications
  tags:
  - Notifications
- name: Content Delivery
  tags:
  - Cds
- name: Audit and Settings
  tags:
  - UserSettingsService
- name: System
  tags:
  - Gateway
  - Deployment
  - License
  - Telemetry
  - LegacyDataCollector
- name: Identity
  tags:
  - users
  - teams
  - tokens
- name: Access Management
  tags:
  - policies
  - roles
  - projects
  - rules
  - Authorization