> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# List OIDC providers

<Info>
  Requires the IAM action **`iam:ListOIDCProviders`**. See [IAM permissions](/iam/permissions) for the full list, what each one covers, and an example policy.
</Info>


## OpenAPI

````yaml /api-reference/specs/iam.yaml get /v1/oidc-providers
openapi: 3.0.3
info:
  title: Basaltic IAM API
  version: 1.0.0
  description: >
    Account identity and access management: service accounts, roles, account
    policies, and account-scoped temporary sessions. Authentication and personal
    sign-in remain in IAM. Organizations, accounts, users, groups, and
    organization policies are managed by the Workspace API.


    Roles and custom policies belong to the selected account. Their global CRNs
    use an empty region and the owning account handle. Shared system policies
    use crn:iam:::policy/<name>. Relationship inputs are classified once as CRN,
    UUID, or name, without syntax fallback.


    AssumeRole resolves the target role's owning account. The caller needs
    source permission and the target role must trust the caller; the resulting
    session uses only the target role's permissions, subject to boundaries and
    session restrictions.
  contact:
    name: Basaltic Support
    email: ping@basaltic.sh
  license:
    name: Proprietary
    url: https://basaltic.sh/terms
servers:
  - url: https://iam.basaltic.sh
    description: Global API endpoint
security:
  - BearerAuth: []
paths:
  /v1/oidc-providers:
    get:
      tags:
        - IAM
      summary: List OIDC providers
      operationId: listOIDCProviders
      parameters:
        - $ref: '#/components/parameters/IAMNameFilter'
        - $ref: '#/components/parameters/IAMCRNFilter'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Marker'
      responses:
        '200':
          description: List OIDC providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCProviderListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    IAMNameFilter:
      name: name
      in: query
      allowEmptyValue: true
      description: >-
        Exact resource name, combined with crn using AND before pagination.
        Empty values are filters. Resources without a name never match.
      schema:
        type: string
    IAMCRNFilter:
      name: crn
      in: query
      allowEmptyValue: true
      description: >-
        Exact returned CRN, combined with name using AND before pagination.
        Malformed or empty CRNs return 400; valid mismatched or foreign CRNs
        return an empty page. Resources without a CRN never match.
        Organization-scoped CRNs use the authenticated organization.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: >-
        Maximum number of items to return. A value above the maximum is clamped
        to it rather than rejected, so a page shorter than the one you asked for
        is normal — page until `meta.has_more` is false, not until a page looks
        short.
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 20
    Marker:
      name: marker
      in: query
      description: >-
        Opaque pagination cursor. Echo back the `meta.marker` value from the
        previous page to fetch the next one; do not construct or parse it. The
        token's internal form varies by endpoint (a resource ID, a timestamp, …)
        and is not guaranteed stable across releases.
      required: false
      schema:
        type: string
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    OIDCProviderListResponse:
      type: object
      required:
        - oidc_providers
        - meta
      properties:
        oidc_providers:
          type: array
          items:
            $ref: '#/components/schemas/OIDCProvider'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    OIDCProvider:
      type: object
      required:
        - id
        - crn
        - name
        - issuer
        - audiences
        - is_system
        - tags
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        crn:
          type: string
          readOnly: true
          example: crn:iam::production:oidc-provider/github
        name:
          type: string
          example: github
        description:
          type: string
        issuer:
          type: string
          format: uri
          example: https://token.actions.githubusercontent.com
          description: >-
            Immutable HTTPS issuer URL. Public discovery and JWKS endpoints are
            required for customer providers.
        audiences:
          type: array
          minItems: 1
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            minLength: 1
            maxLength: 255
          example:
            - basaltic-iam-sts
        is_system:
          type: boolean
          readOnly: true
          description: Platform-managed providers cannot be edited or deleted.
          example: false
        tags:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
          example: 150
        limit:
          type: integer
          description: Number of items per page
          example: 20
        marker:
          type: string
          description: >-
            Opaque cursor for the next page. Pass it back as the `marker` query
            parameter; treat it as a token, not a value to parse.
          example: 550e8400-e29b-41d4-a716-446655440000
        has_more:
          type: boolean
          description: Whether there are more items
          example: true
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Error code identifying the type of error
              example: INVALID_INPUT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameters
            params:
              type: object
              additionalProperties: true
              description: >-
                Optional non-sensitive values for interpolation of localized
                errors, keyed by error code. Never present for server errors.
              example:
                instances: 2
                pools: 0
            request_id:
              type: string
              format: uuid
              description: Request ID for debugging
              example: 550e8400-e29b-41d4-a716-446655440000
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_INPUT
              message: Invalid request parameters
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ACCESS_DENIED
              message: You don't have permission to perform this action
              request_id: 550e8400-e29b-41d4-a716-446655440000
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_FOUND
              message: Resource not found
              request_id: 550e8400-e29b-41d4-a716-446655440000
    Conflict:
      description: Resource conflict (e.g., already exists, invalid state)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: CONFLICT
              message: Resource with this name already exists
              request_id: 550e8400-e29b-41d4-a716-446655440000
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An internal error occurred
              request_id: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        An OAuth 2.0 bearer token, sent as `Authorization: Bearer <token>`.
        This is the recommended way to authenticate.

        Get one by exchanging a service account's access key pair at
        `POST /v1/oauth/token` with `grant_type=client_credentials`. It is the
        standard client-credentials grant, so any OAuth-aware library will
        obtain and refresh it for you.

        ```
        curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
          https://iam.basaltic.sh/v1/oauth/token
        ```

        Tokens last an hour by default. The same access key pair is separately
        your AWS SigV4 credential for the S3-compatible object endpoint, which
        speaks nothing else.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.