IBM

IBM Cloud IAM Identity Services

Manage service IDs, API key identities, trusted profiles, account security settings, and create IAM access tokens.

GitHub

Documentation

📖
Documentation
https://cloud.ibm.com/apidocs/iam-identity-token-api

Specifications

⚙
openapi
https://raw.githubusercontent.com/api-evangelist/ibm/refs/heads/main/openapi/ibm-cloud-iam.yml

Other Resources

🔗
getting-started
https://cloud.ibm.com/docs/account?topic=account-iamoverview
🔗
json-schema
https://raw.githubusercontent.com/api-evangelist/ibm/refs/heads/main/json-schema/ibm-cloud-resource-schema.json
🔗
json-ld-context
https://raw.githubusercontent.com/api-evangelist/ibm/refs/heads/main/json-ld/ibm-context.jsonld

OpenAPI Specification

ibm-cloud-iam.yml Raw ↑ 
openapi: 3.1.0
info:
  title: IBM Cloud IAM 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: [email protected]
  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: Tokens
    description: Create and manage IAM access tokens
  - name: API Keys
    description: Create and manage API keys for users and service IDs
  - name: Service IDs
    description: Create and manage service IDs for applications and services
  - name: Trusted Profiles
    description: Create and manage trusted profiles for federated identities
  - name: Claim Rules
    description: Manage claim rules for trusted profiles
  - name: Policies
    description: Create and manage IAM access policies
  - name: Roles
    description: List and manage IAM roles
  - name: Account Settings
    description: Manage IAM account settings
paths:
  /identity/token:
    post:
      operationId: createAccessToken
      summary: Create an IAM access token
      description: >-
        Create an IAM access token for a user or service ID using an API key,
        refresh token, or delegated refresh token. Tokens are valid for one hour
        and can be refreshed before expiration.
      tags:
        - Tokens
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
              properties:
                grant_type:
                  type: string
                  description: The grant type for token creation.
                  enum:
                    - urn:ibm:params:oauth:grant-type:apikey
                    - urn:ibm:params:oauth:grant-type:delegated-refresh-token
                    - refresh_token
                apikey:
                  type: string
                  description: The API key to use for authentication.
                refresh_token:
                  type: string
                  description: The refresh token to use for token renewal.
                response_type:
                  type: string
                  description: >-
                    Response type for delegated refresh token. Must be
                    cloud_iam when grant_type is
                    urn:ibm:params:oauth:grant-type:delegated-refresh-token.
                  enum:
                    - cloud_iam
      responses:
        '200':
          description: Token created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or expired credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/apikeys:
    get:
      operationId: listApiKeys
      summary: List API keys
      description: >-
        List API keys associated with an IAM ID, account, or service ID. Results
        can be filtered, sorted, and paginated.
      tags:
        - API Keys
      parameters:
        - name: account_id
          in: query
          description: The account ID of the API keys to query.
          schema:
            type: string
        - name: iam_id
          in: query
          description: The IAM ID associated with the API keys.
          schema:
            type: string
        - name: pagesize
          in: query
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: pagetoken
          in: query
          description: Page token from a previous request for pagination.
          schema:
            type: string
        - name: scope
          in: query
          description: Scope of the query, either account or iam_id.
          schema:
            type: string
            enum:
              - account
              - iam_id
        - name: type
          in: query
          description: Filter by API key type.
          schema:
            type: string
            enum:
              - user
              - serviceid
        - name: sort
          in: query
          description: Field to sort by.
          schema:
            type: string
        - name: order
          in: query
          description: Sort order.
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: List of API keys returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createApiKey
      summary: Create an API key
      description: >-
        Create a new API key for a user or service ID. The API key value is
        returned only at creation time.
      tags:
        - API Keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '201':
          description: API key created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
          headers:
            Entity-Tag:
              description: The version identifier for the created API key.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/apikeys/details:
    get:
      operationId: getApiKeysDetails
      summary: Get API key details by value
      description: >-
        Retrieve details of an API key by providing the key value in the
        IAM-ApiKey header.
      tags:
        - API Keys
      parameters:
        - name: IAM-ApiKey
          in: header
          description: The API key value to look up.
          schema:
            type: string
        - name: include_history
          in: query
          description: Include activity history of the API key.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: API key details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/apikeys/{id}:
    get:
      operationId: getApiKey
      summary: Get an API key
      description: Retrieve details for a specific API key by its unique identifier.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ApiKeyId'
        - name: include_history
          in: query
          description: Include the history of the API key.
          schema:
            type: boolean
            default: false
        - name: include_activity
          in: query
          description: Include the activity of the API key.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: API key details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateApiKey
      summary: Update an API key
      description: Update properties of an existing API key such as name and description.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ApiKeyId'
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiKeyRequest'
      responses:
        '200':
          description: API key updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: deleteApiKey
      summary: Delete an API key
      description: Remove an API key permanently. This action cannot be undone.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ApiKeyId'
      responses:
        '204':
          description: API key deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/apikeys/{id}/lock:
    post:
      operationId: lockApiKey
      summary: Lock an API key
      description: >-
        Lock an API key to prevent it from being deleted or modified. Locked keys
        remain active and can still be used for authentication.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ApiKeyId'
      responses:
        '200':
          description: API key locked successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: unlockApiKey
      summary: Unlock an API key
      description: Unlock a previously locked API key to allow modifications and deletion.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ApiKeyId'
      responses:
        '200':
          description: API key unlocked successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/apikeys/{id}/disable:
    post:
      operationId: disableApiKey
      summary: Disable an API key
      description: >-
        Disable an API key to prevent it from being used for authentication. The
        key can be re-enabled later.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ApiKeyId'
      responses:
        '200':
          description: API key disabled successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: enableApiKey
      summary: Enable an API key
      description: Re-enable a previously disabled API key for authentication.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/ApiKeyId'
      responses:
        '200':
          description: API key enabled successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/serviceids/:
    get:
      operationId: listServiceIds
      summary: List service IDs
      description: >-
        List service IDs in an account. Results can be filtered by name, sorted,
        and paginated.
      tags:
        - Service IDs
      parameters:
        - name: account_id
          in: query
          description: The account ID of the service IDs to query.
          schema:
            type: string
        - name: name
          in: query
          description: Filter service IDs by name.
          schema:
            type: string
        - name: pagesize
          in: query
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: pagetoken
          in: query
          description: Page token from a previous request for pagination.
          schema:
            type: string
        - name: sort
          in: query
          description: Field to sort results by.
          schema:
            type: string
        - name: order
          in: query
          description: Sort order.
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: List of service IDs returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceIdList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createServiceId
      summary: Create a service ID
      description: >-
        Create a new service ID for an IBM Cloud account. Service IDs are used
        by applications and services to authenticate with IBM Cloud.
      tags:
        - Service IDs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceIdRequest'
      responses:
        '201':
          description: Service ID created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/serviceids/{id}:
    get:
      operationId: getServiceId
      summary: Get a service ID
      description: Retrieve details of a service ID by its unique identifier.
      tags:
        - Service IDs
      parameters:
        - $ref: '#/components/parameters/ServiceIdParam'
        - name: include_history
          in: query
          description: Include the history of the service ID.
          schema:
            type: boolean
            default: false
        - name: include_activity
          in: query
          description: Include the activity of the service ID.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Service ID details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateServiceId
      summary: Update a service ID
      description: >-
        Update properties of an existing service ID such as name and
        description.
      tags:
        - Service IDs
      parameters:
        - $ref: '#/components/parameters/ServiceIdParam'
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceIdRequest'
      responses:
        '200':
          description: Service ID updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: deleteServiceId
      summary: Delete a service ID
      description: >-
        Delete a service ID and all associated API keys. This action cannot be
        undone.
      tags:
        - Service IDs
      parameters:
        - $ref: '#/components/parameters/ServiceIdParam'
      responses:
        '204':
          description: Service ID deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/serviceids/{id}/lock:
    post:
      operationId: lockServiceId
      summary: Lock a service ID
      description: >-
        Lock a service ID to prevent modification or deletion. Locked service
        IDs remain active.
      tags:
        - Service IDs
      parameters:
        - $ref: '#/components/parameters/ServiceIdParam'
      responses:
        '200':
          description: Service ID locked successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: unlockServiceId
      summary: Unlock a service ID
      description: Unlock a previously locked service ID.
      tags:
        - Service IDs
      parameters:
        - $ref: '#/components/parameters/ServiceIdParam'
      responses:
        '200':
          description: Service ID unlocked successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/profiles:
    get:
      operationId: listProfiles
      summary: List trusted profiles
      description: >-
        List trusted profiles in an account. Trusted profiles allow federated
        users to establish trust with IBM Cloud.
      tags:
        - Trusted Profiles
      parameters:
        - name: account_id
          in: query
          required: true
          description: The account ID to list trusted profiles for.
          schema:
            type: string
        - name: name
          in: query
          description: Filter profiles by name.
          schema:
            type: string
        - name: pagesize
          in: query
          description: Number of results per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: pagetoken
          in: query
          description: Page token from a previous request.
          schema:
            type: string
        - name: sort
          in: query
          description: Field to sort by.
          schema:
            type: string
        - name: order
          in: query
          description: Sort order.
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: include_history
          in: query
          description: Include the history of the profiles.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: List of trusted profiles returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustedProfileList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProfile
      summary: Create a trusted profile
      description: >-
        Create a new trusted profile for federated users to establish trust with
        IBM Cloud resources.
      tags:
        - Trusted Profiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProfileRequest'
      responses:
        '201':
          description: Trusted profile created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustedProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/profiles/{profile-id}:
    get:
      operationId: getProfile
      summary: Get a trusted profile
      description: Retrieve details of a specific trusted profile.
      tags:
        - Trusted Profiles
      parameters:
        - $ref: '#/components/parameters/ProfileId'
        - name: include_activity
          in: query
          description: Include the activity of the profile.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Trusted profile details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustedProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateProfile
      summary: Update a trusted profile
      description: Update properties of an existing trusted profile.
      tags:
        - Trusted Profiles
      parameters:
        - $ref: '#/components/parameters/ProfileId'
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProfileRequest'
      responses:
        '200':
          description: Trusted profile updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustedProfile'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: deleteProfile
      summary: Delete a trusted profile
      description: >-
        Delete a trusted profile and its associated claim rules and links. This
        action cannot be undone.
      tags:
        - Trusted Profiles
      parameters:
        - $ref: '#/components/parameters/ProfileId'
      responses:
        '204':
          description: Trusted profile deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/profiles/{profile-id}/rules:
    get:
      operationId: listClaimRules
      summary: List claim rules for a trusted profile
      description: Retrieve all claim rules defined for a specific trusted profile.
      tags:
        - Claim Rules
      parameters:
        - $ref: '#/components/parameters/ProfileId'
      responses:
        '200':
          description: List of claim rules returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimRuleList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createClaimRule
      summary: Create a claim rule
      description: >-
        Create a claim rule for a trusted profile. Claim rules define conditions
        that federated users must meet to apply the profile.
      tags:
        - Claim Rules
      parameters:
        - $ref: '#/components/parameters/ProfileId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClaimRuleRequest'
      responses:
        '201':
          description: Claim rule created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimRule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/profiles/{profile-id}/rules/{rule-id}:
    get:
      operationId: getClaimRule
      summary: Get a claim rule
      description: Retrieve details of a specific claim rule in a trusted profile.
      tags:
        - Claim Rules
      parameters:
        - $ref: '#/components/parameters/ProfileId'
        - $ref: '#/components/parameters/RuleId'
      responses:
        '200':
          description: Claim rule details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimRule'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateClaimRule
      summary: Update a claim rule
      description: Update an existing claim rule for a trusted profile.
      tags:
        - Claim Rules
      parameters:
        - $ref: '#/components/parameters/ProfileId'
        - $ref: '#/components/parameters/RuleId'
        - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClaimRuleRequest'
      responses:
        '200':
          description: Claim rule updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimRule'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: deleteClaimRule
      summary: Delete a claim rule
      description: Remove a claim rule from a trusted profile.
      tags:
        - Claim Rules
      parameters:
        - $ref: '#/components/parameters/ProfileId'
        - $ref: '#/components/parameters/RuleId'
      responses:
        '204':
          description: Claim rule deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /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'
  /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 t

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ibm/refs/heads/main/openapi/ibm-cloud-iam.yml