openapi: 3.1.0
info:
  title: IBM Cloud IAM API Keys Policies API
  description: The IBM Cloud Identity and Access Management (IAM) API enables you to manage IAM access tokens, API keys, service IDs, trusted profiles, and access policies. Use this API to authenticate identities, authorize access to IBM Cloud resources, and manage the full lifecycle of identity and policy objects within your IBM Cloud account.
  version: 1.0.0
  contact:
    name: IBM Cloud
    url: https://cloud.ibm.com
    email: cloud@ibm.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-ibm-api-source: https://cloud.ibm.com/apidocs/iam-identity-token-api
servers:
- url: https://iam.cloud.ibm.com
  description: IBM Cloud IAM production endpoint
security:
- bearerAuth: []
tags:
- name: Policies
  description: Create and manage IAM access policies
paths:
  /v1/policies:
    get:
      operationId: listPolicies
      summary: List access policies
      description: List access policies in an account. Results can be filtered by IAM ID, access group, service type, and state.
      tags:
      - Policies
      parameters:
      - name: account_id
        in: query
        required: true
        description: The account ID to list policies for.
        schema:
          type: string
      - name: iam_id
        in: query
        description: Filter by the IAM ID of the subject.
        schema:
          type: string
      - name: access_group_id
        in: query
        description: Filter by access group ID.
        schema:
          type: string
      - name: type
        in: query
        description: Filter by policy type.
        schema:
          type: string
          enum:
          - access
          - authorization
      - name: service_type
        in: query
        description: Filter by service type.
        schema:
          type: string
      - name: state
        in: query
        description: Filter by policy state.
        schema:
          type: string
          enum:
          - active
          - deleted
      - name: limit
        in: query
        description: Maximum number of policies to return.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - name: start
        in: query
        description: Pagination start token.
        schema:
          type: string
      responses:
        '200':
          description: List of access policies returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPolicy
      summary: Create an access policy
      description: Create a new access policy to grant a subject access to a resource. A policy defines a subject, roles, and resources.
      tags:
      - Policies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePolicyRequest'
      responses:
        '201':
          description: Access policy created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
  /v1/policies/{policy_id}:
    get:
      operationId: getPolicy
      summary: Get an access policy
      description: Retrieve details of a specific access policy.
      tags:
      - Policies
      parameters:
      - $ref: '#/components/parameters/PolicyId'
      responses:
        '200':
          description: Access policy details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replacePolicy
      summary: Replace an access policy
      description: Replace an existing access policy with an updated definition. The entire policy is replaced.
      tags:
      - Policies
      parameters:
      - $ref: '#/components/parameters/PolicyId'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePolicyRequest'
      responses:
        '200':
          description: Access policy replaced successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: deletePolicy
      summary: Delete an access policy
      description: Remove an access policy. This action cannot be undone.
      tags:
      - Policies
      parameters:
      - $ref: '#/components/parameters/PolicyId'
      responses:
        '204':
          description: Access policy deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePolicyState
      summary: Update policy state
      description: Activate or deactivate an existing access policy.
      tags:
      - Policies
      parameters:
      - $ref: '#/components/parameters/PolicyId'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - state
              properties:
                state:
                  type: string
                  description: The desired state for the policy.
                  enum:
                  - active
                  - deleted
      responses:
        '200':
          description: Policy state updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
components:
  parameters:
    PolicyId:
      name: policy_id
      in: path
      required: true
      description: The unique identifier of the access policy.
      schema:
        type: string
    IfMatch:
      name: If-Match
      in: header
      required: true
      description: The entity tag value from a previous GET request used for optimistic concurrency control.
      schema:
        type: string
  schemas:
    PolicySubject:
      type: object
      description: A subject in a policy, defining who the policy applies to.
      properties:
        attributes:
          type: array
          description: The attributes that identify the subject.
          items:
            $ref: '#/components/schemas/PolicyAttribute'
    ResponseContext:
      type: object
      description: Context metadata for paginated API responses.
      properties:
        transaction_id:
          type: string
          description: The unique transaction ID for the request.
        operation:
          type: string
          description: The operation that was performed.
        user_agent:
          type: string
          description: The user agent string from the request.
        url:
          type: string
          description: The URL of the request.
        instance_id:
          type: string
          description: The instance ID of the service.
        thread_id:
          type: string
          description: The thread ID of the request.
        host:
          type: string
          description: The host that served the request.
        start_time:
          type: string
          description: Timestamp when the request started.
        end_time:
          type: string
          description: Timestamp when the request ended.
        elapsed_time:
          type: string
          description: The elapsed time of the request.
        cluster_name:
          type: string
          description: The cluster name of the service.
    CreatePolicyRequest:
      type: object
      description: Request body for creating an access policy.
      required:
      - type
      - subjects
      - roles
      - resources
      properties:
        type:
          type: string
          description: The type of the policy.
          enum:
          - access
          - authorization
        subjects:
          type: array
          description: The subjects the policy applies to.
          items:
            $ref: '#/components/schemas/PolicySubject'
        roles:
          type: array
          description: The roles granted by the policy.
          items:
            $ref: '#/components/schemas/PolicyRole'
        resources:
          type: array
          description: The resources the policy applies to.
          items:
            $ref: '#/components/schemas/PolicyResource'
        description:
          type: string
          description: A description of the policy.
    PolicyList:
      type: object
      description: A paginated list of access policies.
      properties:
        policies:
          type: array
          description: The list of policies.
          items:
            $ref: '#/components/schemas/Policy'
    ErrorResponse:
      type: object
      description: An error response from the IAM API.
      properties:
        context:
          $ref: '#/components/schemas/ResponseContext'
        status_code:
          type: integer
          description: The HTTP status code.
        errors:
          type: array
          description: The list of errors.
          items:
            type: object
            properties:
              code:
                type: string
                description: The error code.
              message:
                type: string
                description: A human-readable error message.
              details:
                type: string
                description: Additional error details.
              more_info:
                type: string
                description: A URL for more information about the error.
        trace:
          type: string
          description: A trace identifier for debugging.
    PolicyRole:
      type: object
      description: A role assigned in a policy.
      properties:
        role_id:
          type: string
          description: The CRN of the role.
        display_name:
          type: string
          description: The display name of the role.
        description:
          type: string
          description: A description of the role.
    PolicyResource:
      type: object
      description: A resource in a policy, defining what the policy applies to.
      properties:
        attributes:
          type: array
          description: The attributes that identify the resource.
          items:
            $ref: '#/components/schemas/PolicyAttribute'
    PolicyAttribute:
      type: object
      description: An attribute used to identify a subject or resource in a policy.
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: The attribute name.
        value:
          type: string
          description: The attribute value.
        operator:
          type: string
          description: The operator for value comparison.
          enum:
          - stringEquals
          - stringMatch
          - stringExists
    Policy:
      type: object
      description: An IAM access policy that grants a subject a set of roles on a resource.
      properties:
        id:
          type: string
          description: The unique identifier of the policy.
        type:
          type: string
          description: The type of the policy.
          enum:
          - access
          - authorization
        description:
          type: string
          description: A description of the policy.
        subjects:
          type: array
          description: The subjects the policy applies to.
          items:
            $ref: '#/components/schemas/PolicySubject'
        roles:
          type: array
          description: The roles granted by the policy.
          items:
            $ref: '#/components/schemas/PolicyRole'
        resources:
          type: array
          description: The resources the policy applies to.
          items:
            $ref: '#/components/schemas/PolicyResource'
        href:
          type: string
          description: The URL of the policy.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the policy was created.
        created_by_id:
          type: string
          description: The IAM ID of the user who created the policy.
        last_modified_at:
          type: string
          format: date-time
          description: Timestamp when the policy was last modified.
        last_modified_by_id:
          type: string
          description: The IAM ID of the user who last modified the policy.
        state:
          type: string
          description: The current state of the policy.
          enum:
          - active
          - deleted
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed or credentials are missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: A conflict occurred, typically from an If-Match version mismatch.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'IAM access token obtained from the /identity/token endpoint. Pass as Authorization: Bearer <token>.'