openapi: 3.1.0
info:
  title: IBM Cloud IAM API Keys Roles 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: Roles
  description: List and manage IAM roles
paths:
  /v2/roles:
    get:
      operationId: listRoles
      summary: List IAM roles
      description: List system-defined and custom roles available in the account. Results can be filtered by service name.
      tags:
      - Roles
      parameters:
      - name: account_id
        in: query
        description: The account ID to list custom roles for.
        schema:
          type: string
      - name: service_name
        in: query
        description: Filter roles by the service they apply to.
        schema:
          type: string
      - name: source_service_name
        in: query
        description: Filter by the source service name for authorization policies.
        schema:
          type: string
      - name: policy_type
        in: query
        description: Filter by policy type.
        schema:
          type: string
      - name: service_group_id
        in: query
        description: Filter by the service group ID.
        schema:
          type: string
      responses:
        '200':
          description: List of roles returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRole
      summary: Create a custom role
      description: Create a custom role with a set of actions for a specific service. Custom roles extend the built-in platform and service roles.
      tags:
      - Roles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleRequest'
      responses:
        '201':
          description: Custom role created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
  /v2/roles/{role_id}:
    get:
      operationId: getRole
      summary: Get a role
      description: Retrieve details of a specific role.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      responses:
        '200':
          description: Role details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replaceRole
      summary: Replace a custom role
      description: Replace the definition of an existing custom role with an updated set of actions.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleRequest'
      responses:
        '200':
          description: Role replaced successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: deleteRole
      summary: Delete a custom role
      description: Remove a custom role. System-defined roles cannot be deleted.
      tags:
      - Roles
      parameters:
      - $ref: '#/components/parameters/RoleIdParam'
      responses:
        '204':
          description: Role deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    RoleList:
      type: object
      description: A list of IAM roles.
      properties:
        custom_roles:
          type: array
          description: The list of custom roles.
          items:
            $ref: '#/components/schemas/Role'
        service_roles:
          type: array
          description: The list of service-defined roles.
          items:
            $ref: '#/components/schemas/Role'
        system_roles:
          type: array
          description: The list of system-defined platform roles.
          items:
            $ref: '#/components/schemas/Role'
    Role:
      type: object
      description: An IAM role that defines a set of actions.
      properties:
        id:
          type: string
          description: The unique identifier of the role.
        display_name:
          type: string
          description: The display name of the role.
        description:
          type: string
          description: A description of the role.
        actions:
          type: array
          description: The list of actions granted by this role.
          items:
            type: string
        crn:
          type: string
          description: The CRN of the role.
        name:
          type: string
          description: The name identifier of the role.
        account_id:
          type: string
          description: The account ID for custom roles.
        service_name:
          type: string
          description: The service this role applies to.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the role was created.
        created_by_id:
          type: string
          description: The IAM ID of the user who created the role.
        last_modified_at:
          type: string
          format: date-time
          description: Timestamp when the role was last modified.
        last_modified_by_id:
          type: string
          description: The IAM ID of the user who last modified the role.
    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.
    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.
    CreateRoleRequest:
      type: object
      description: Request body for creating a custom role.
      required:
      - display_name
      - actions
      - name
      - account_id
      - service_name
      properties:
        display_name:
          type: string
          description: The display name for the custom role.
        actions:
          type: array
          description: The actions granted by this role.
          items:
            type: string
        name:
          type: string
          description: The programmatic name identifier for the role.
        account_id:
          type: string
          description: The account ID for the custom role.
        service_name:
          type: string
          description: The service this role applies to.
        description:
          type: string
          description: A description of the custom role.
  parameters:
    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
    RoleIdParam:
      name: role_id
      in: path
      required: true
      description: The unique identifier of the role.
      schema:
        type: string
  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'
    NotFound:
      description: The requested resource was not found.
      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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'IAM access token obtained from the /identity/token endpoint. Pass as Authorization: Bearer <token>.'