openapi: 3.0.0
info:
  description: >
    The Credential Management REST API provides a comprehensive interface to list and delete enrolled 
    credentials within the WSO2 Identity Server. The administrators who are assigned with required privileges
    (with scopes internal_user_credential_mgt_view and internal_user_credential_mgt_delete) are able to 
    perform these operations.
  version: '1.0'
  title: WSO2 Identity Server - User Credential Management Rest API
  contact:
    name: WSO2
    url: https://wso2.com/identity-server/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

security:
  - OAuth2: []
  - BasicAuth: []

servers:
  - url: https://{server-url}/t/{tenant-domain}/api/server/v1
    variables:
      tenant-domain:
        default: carbon.super
      server-url:
        default: localhost:9443

paths:
  /users/{user-id}/credentials:
    get:
      summary: Get all credentials for a user
      description: Retrieves a list of all user-enrolled credentials. Requires administrative privileges with scope internal_user_credential_mgt_view. This API currently supports passkey and push authentication credentials.
      operationId: getUserCredentialsById
      tags:
        - Get User Credentials
      parameters:
        - name: user-id
          in: path
          description: The unique identifier of the user.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Credential'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{user-id}/credentials/{type}/{credential-id}:
    delete:
      summary: Delete a user-enrolled credential.
      description: Deletes a specific enrolled credential for a user. Requires administrative privileges with scope internal_user_credential_mgt_delete.
      operationId: deleteUserCredentialById
      tags:
        - Delete User Credential
      parameters:
        - name: user-id
          in: path
          description: The unique identifier of the user.
          required: true
          schema:
            type: string
        - name: type
          in: path
          description: The type of the credential.
          required: true
          schema:
            type: string
            enum: [passkey, push-auth]
        - name: credential-id
          in: path
          description: The unique identifier of the device to be deleted.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: User Credential Deleted.
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Credential:
      type: object
      properties:
        credentialId:
          type: string
          description: The unique identifier for the credential.
          example: 'a5a81c76-27a3-42d4-82a8-55285d82a4a1'
        displayName:
          type: string
          description: A user-friendly name for the credential.
          example: "YubiKey 5C"
        type:
          type: string
          description: The type of the credential.
          enum: [passkey, push-auth]
    Error:
      type: object
      properties:
        code:
          type: string
          description: A unique, machine-readable error code following the WSO2 standard.
          example: 'CM-60401'
        message:
          type: string
          description: A human-readable summary of the error.
          example: 'User not found.'
        description:
          type: string
          description: A more detailed explanation of the error.
          example: 'The user specified by the user-id does not exist in the system.'

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://localhost:9443/oauth2/authorize
          tokenUrl: https://localhost:9443/oauth2/token
          scopes:
            read: internal_user_credential_mgt_view
            delete: internal_user_credential_mgt_delete

