openapi: 3.1.0
info:
  title: IBM Cloud IAM API Keys 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: API Keys
  description: Create and manage API keys for users and service IDs
paths:
  /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'
components:
  schemas:
    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.
    ApiKeyList:
      type: object
      description: A paginated list of API keys.
      properties:
        context:
          $ref: '#/components/schemas/ResponseContext'
        offset:
          type: integer
          description: The offset of the current page.
        limit:
          type: integer
          description: The number of results per page.
        first:
          type: string
          description: URL to the first page of results.
        previous:
          type: string
          description: URL to the previous page of results.
        next:
          type: string
          description: URL to the next page of results.
        apikeys:
          type: array
          description: The list of API keys.
          items:
            $ref: '#/components/schemas/ApiKey'
    CreateApiKeyRequest:
      type: object
      description: Request body for creating an API key.
      required:
      - name
      - iam_id
      properties:
        name:
          type: string
          description: The name of the API key.
        iam_id:
          type: string
          description: The IAM ID that the API key authenticates.
        description:
          type: string
          description: A description of the API key.
        account_id:
          type: string
          description: The account ID for the API key.
        apikey:
          type: string
          description: Specify the API key value. If omitted, the system generates one automatically.
        store_value:
          type: boolean
          description: Whether to store the API key value in the system.
        support_sessions:
          type: boolean
          description: Whether sessions are supported for this API key.
        action_when_leaked:
          type: string
          description: Action to perform when the API key is leaked.
        expires_at:
          type: string
          format: date-time
          description: Expiration date and time for the API key.
    ApiKey:
      type: object
      description: An IAM API key used for authentication.
      properties:
        id:
          type: string
          description: The unique identifier of the API key.
        entity_tag:
          type: string
          description: The version identifier for optimistic concurrency control.
        crn:
          type: string
          description: The Cloud Resource Name for this API key.
        locked:
          type: boolean
          description: Whether the API key is locked against modification.
        disabled:
          type: boolean
          description: Whether the API key is disabled for authentication.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the API key was created.
        created_by:
          type: string
          description: The IAM ID of the user who created the API key.
        modified_at:
          type: string
          format: date-time
          description: Timestamp when the API key was last modified.
        name:
          type: string
          description: The name of the API key.
        support_sessions:
          type: boolean
          description: Whether sessions are supported for this API key.
        action_when_leaked:
          type: string
          description: Action to perform when the API key is leaked.
        description:
          type: string
          description: A description of the API key.
        iam_id:
          type: string
          description: The IAM ID associated with this API key.
        account_id:
          type: string
          description: The account ID that this API key belongs to.
        apikey:
          type: string
          description: The API key value. Only included at creation time.
        history:
          type: array
          description: History of changes to the API key.
          items:
            $ref: '#/components/schemas/ActivityEntry'
        activity:
          $ref: '#/components/schemas/Activity'
    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.
    Activity:
      type: object
      description: Activity information for an identity resource.
      properties:
        last_authn:
          type: string
          description: Timestamp of the last authentication using this identity.
        authn_count:
          type: integer
          description: The number of authentications using this identity.
    ActivityEntry:
      type: object
      description: A history entry for an identity resource.
      properties:
        timestamp:
          type: string
          description: Timestamp of the activity.
        iam_id:
          type: string
          description: The IAM ID that performed the action.
        iam_id_account:
          type: string
          description: The account ID of the actor.
        action:
          type: string
          description: The action that was performed.
        params:
          type: array
          description: Parameters associated with the action.
          items:
            type: string
        message:
          type: string
          description: A message describing the action.
    UpdateApiKeyRequest:
      type: object
      description: Request body for updating an API key.
      properties:
        name:
          type: string
          description: The updated name of the API key.
        description:
          type: string
          description: The updated description of the API key.
        support_sessions:
          type: boolean
          description: Whether sessions are supported for this API key.
        action_when_leaked:
          type: string
          description: Action to perform when the API key is leaked.
        expires_at:
          type: string
          format: date-time
          description: Expiration date and time for the API key.
  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
    ApiKeyId:
      name: id
      in: path
      required: true
      description: The unique identifier of the API key.
      schema:
        type: string
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      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'
    Unauthorized:
      description: Authentication failed or credentials are missing.
      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>.'