--- title: "List providers" method: GET path: "/zones/{zoneId}/providers" tags: ["Providers"] --- # List providers `GET /zones/{zoneId}/providers` ## Request - Base URL: `https://docs.keycard.ai` (the document declares no server; this is the origin it was published from) - URL: `https://docs.keycard.ai/zones/{zoneId}/providers` - Auth: one of: - HTTP bearer - OAuth 2 - Client credentials - Token URL: `/service-account-token` Returns a paginated list of providers in the specified zone. Use cursor pagination via `after`/`before`. Sort: comma-separated field list; prefix with `-` for descending. Use `expand[]=total_count` to include the matching row count. Filter by exact slug via `filter[slug]`, exact identifier via `filter[identifier]` and provider type via `filter[type]`. Search via `query[name]` / `query[identifier]` / `query[]` (substring match, OR'd across repeated values). `query[]` matches against name and identifier. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of provider IDs — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested provider that exists in the zone, in a single page. Unknown or malformed IDs are silently omitted. ## Path parameters - `zoneId` string, required ## Query parameters - `after` string - `before` string - `limit` integer - `expand[]` union - 'total_count' - string[] - `slug` string - `identifier` string - `type` 'external' | 'keycard-vault' | 'keycard-sts' - `filter[slug]` union - string: Filter by exact provider slug - string[] - `filter[identifier]` union - string: Filter by exact provider identifier - string[] - `filter[type]` union - 'external' | 'keycard-vault' | 'keycard-sts': Filter by provider type - string[] - `filter[id]` union - string: Restrict results to providers with this ID. Repeatable, max 100. Mutually exclusive with after/before. - string[] - `query[name]` union - string: Search by name (substring match) - string[] - `query[identifier]` union - string: Search by identifier (substring match) - string[] - `query[]` union - string: Search across name and identifier (substring match) - string[] - `sort` string - `cursor` string ## Response `200` Default Response - object - `items` IamProvider[], required - `id` string, required: Unique identifier of the provider - `organization_id` string, required: Organization that owns this provider - `zone_id` string, required: Zone this provider belongs to - `slug` string, required: URL-safe identifier, unique within the zone - `name` string, required: Human-readable name - `description` string, nullable: Human-readable description - `identifier` string, required: User specified identifier, unique within the zone - `type` 'external' | 'keycard-vault' | 'keycard-sts' - `client_id` string, nullable: OAuth 2.0 client identifier - `client_secret_set` boolean: Indicates whether a client secret is configured - `protocols` object, nullable: Protocol-specific configuration - `oauth2` IamProviderOAuth2Protocol, nullable: OAuth 2.0 protocol configuration - `issuer` string, uri, required: OIDC issuer URL used for discovery and token validation. - `authorization_endpoint` string, uri, nullable - `token_endpoint` string, uri, nullable - `registration_endpoint` string, uri, nullable - `jwks_uri` string, uri, nullable - `code_challenge_methods_supported` string[], nullable - `scopes_supported` string[], nullable - `authorization_resource_enabled` boolean, nullable: Whether to include the resource parameter in authorization requests. - `authorization_resource_parameter` string, nullable: The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true. - `scope_parameter` string, nullable: The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope". - `scope_separator` string, nullable: The separator character for scope values. Defaults to " " (space). Slack v2 uses ",". - `token_response_access_token_pointer` string, nullable: Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token". - `authorization_parameters` object, nullable: Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline). - `openid` IamProviderOpenIDProtocol, nullable: OpenID Connect protocol configuration - `userinfo_endpoint` string, uri, nullable - `user_identifier_claim` string, nullable: Name of a top-level string claim in this provider's ID Token to use as the user identifier on user creation. When not set, the user's Keycard ID is used. - `scopes` string[], nullable: Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email). - `single_logout_enabled` boolean, nullable: When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false. - `metadata` object, nullable: Provider metadata - `icon_url` string, uri: Icon URL - `owner_type` 'platform' | 'customer', required: Who owns this provider. Platform-owned providers cannot be modified via API. - `created_at` string, date-time, required: Entity creation timestamp - `updated_at` string, date-time, required: Entity update timestamp - `page_info` IamPageInfo, required: Pagination information - `has_next_page` boolean, required: Whether there are more items after the current page - `has_previous_page` boolean, required: Whether there are items before the current page - `start_cursor` string, nullable: Cursor pointing to the first item in the current page - `end_cursor` string, nullable: Cursor pointing to the last item in the current page - `pagination` IamPagination, required: Cursor-based pagination metadata - `after_cursor` string, required: An opaque cursor used for paginating through a list of results - `before_cursor` string, required: An opaque cursor used for paginating through a list of results - `total_count` integer: Total number of items matching the query. Only included when expand[]=total_count is requested. ## Other responses - `400`: Error response - `default`: Error response ## Changes - **2026-10-16** `0cfaff865771`: 3 breaking, 3 warning, 10 info - the `page_info` response's property type changed from `object` to no type for status `200` - removed the required property `page_info/has_next_page` from the response with the `200` status - removed the required property `page_info/has_previous_page` from the response with the `200` status - removed the optional property `items/items/protocols/openid/external_id_claim` from the response with the `200` status - …12 more - **2026-08-26** `d65d51379d93`: 3 info - added the new optional `query` request parameter `filter[id]` - added the optional property `items/items/metadata/icon_url` to the response with the `200` status - added the optional property `items/items/protocols/openid/external_id_claim` to the response with the `200` status - **2026-07-01** `2f5033ed4491`: 1 info - added the optional property `items/items/protocols/openid/single_logout_enabled` to the response with the `200` status - **2026-05-22** `ffb6f697525f`: 1 info - added the optional property `items/items/protocols/openid/scopes` to the response with the `200` status - **2026-04-02** `aee6e66de0d3`: 1 info - added the optional property `items/items/protocols/openid/user_identifier_claim` to the response with the `200` status [Operation history](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/changes/zones/:zoneId/providers/get.md) --- [API](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api.md) - [All operations](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keycardai/apis/keycard-ai-keycard-api/revisions/0dee67e0a73a?raw)