--- title: "List delegated grants" method: GET path: "/zones/{zoneId}/delegated-grants" tags: ["Delegated Grants"] --- # List delegated grants `GET /zones/{zoneId}/delegated-grants` ## 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}/delegated-grants` - Auth: one of: - HTTP bearer - OAuth 2 - Client credentials - Token URL: `/service-account-token` Returns a paginated list of delegated grants in the specified zone. Can be filtered by user, resource, or status. 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. ## Path parameters - `zoneId` string, required ## Query parameters - `user_id` string - `resource_id` string - `active` 'true' - `status` 'active' | 'expired' | 'revoked' - `after` string - `before` string - `limit` integer - `expand[]` union - 'total_count' - string[] - `sort` string ## Response `200` Default Response - object - `items` IamDelegatedGrant[], required - `id` string, required: Unique identifier of the delegated grant - `organization_id` string, required: Organization that owns this grant - `zone_id` string, required: Zone this grant belongs to - `user_id` string, required: Reference to the user granting permission - `resource_id` string, required: ID of resource receiving grant - `provider_id` string, required: ID of the provider that issued this grant - `scopes` string[], required: Granted OAuth scopes - `created_at` string, date-time, required: Entity creation timestamp - `updated_at` string, date-time, required: Entity update timestamp - `expires_at` string, date-time, required: Date when grant expires - `status` 'active' | 'expired' | 'revoked', required - `refreshed_at` string, date-time: Timestamp when this grant's tokens were last refreshed. Omitted if grant was never refreshed. - `refresh_token_set` boolean, required: Indicates whether a refresh token is stored for this grant. Grants with refresh tokens can be refreshed even after access token expiration. - `active` boolean: Whether the grant is currently active (deprecated - use status instead) - `resource` IamResource: A Resource is a system that exposes protected information or functionality. It requires authentication of the requesting actor, which may be a user or application, before allowing access. - `id` string, required: Unique identifier of the resource - `organization_id` string, required: Organization that owns this resource - `zone_id` string, required: Zone this resource belongs to - `slug` string, required: URL-safe identifier, unique within the zone - `identifier` string, required: User specified identifier, unique within the zone - `name` string, required: Human-readable name - `description` string, nullable: Human-readable description - `scopes` string[], nullable: Scopes supported by the resource - `credential_provider_id` string: ID of the credential provider for this resource - `credential_provider` IamProvider: A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. - `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 - `application_id` string: ID of the application that provides this resource - `application` IamApplication: An Application is a software system with an associated identity that can access Resources. It may act on its own behalf (machine-to-machine) or on behalf of a user (delegated access). - `id` string, required: Unique identifier of the application - `organization_id` string, required: Organization that owns this application - `zone_id` string, required: Zone this application belongs to - `slug` string, required: URL-safe identifier, unique within the zone - `identifier` string, required: User specified identifier, unique within the zone - `name` string, required: Human-readable name - `description` string, nullable: Human-readable description - `metadata` IamMetadata: Entity metadata - `docs_url` string, uri: Documentation URL - `icon_url` string, uri: Icon URL - `protocols` object, nullable: Protocol-specific configuration - `oauth2` IamApplicationOAuth2Protocol, nullable: OAuth 2.0 protocol configuration - `redirect_uris` string[], nullable: OAuth 2.0 redirect URIs for this application - `post_logout_redirect_uris` string[], nullable: OAuth 2.0 post-logout redirect URIs for this application - `dependencies_count` integer, required: Number of resource dependencies - `owner_type` 'platform' | 'customer', required: Who owns this application. Platform-owned applications cannot be modified via API. - `consent` 'implicit' | 'required', required: Consent mode for the application. 'implicit' means consent is automatically granted, 'required' means explicit user consent is needed. - `created_at` string, date-time, required: Entity creation timestamp - `updated_at` string, date-time, required: Entity update timestamp - `application_type` 'native' | 'web', required: The expected type of client for this credential. Native clients must use localhost URLs for redirect_uris or URIs with custom schemes. Web clients must use https URLs and must not use localhost as the hostname. - `prefix` boolean, required: When true, the resource identifier is treated as a URI prefix, protecting all URLs that share the identifier as a prefix at path/query/fragment boundaries. Protocol and hostname must match exactly. When multiple prefix resources satisfy an identifier query, the resource with the longest prefix is matched. - `credential_lifetime_seconds` integer, nullable: Credential lifetime override in seconds. When set, overrides the default credential lifetime for this resource. When absent, the default from the provider or zone is used. - `when_accessing` string[]: List of resource IDs that, when accessed, make this dependency available. Only present when this resource is returned as a dependency. - `metadata` IamMetadata: Entity metadata - `docs_url` string, uri: Documentation URL - `icon_url` string, uri: Icon URL - `owner_type` 'platform' | 'customer', required: Who owns this resource. Platform-owned resources cannot be modified via API. - `created_at` string, date-time, required: Entity creation timestamp - `updated_at` string, date-time, required: Entity update timestamp - `user` IamUser: An authenticated user entity - `id` string, required: Unique identifier of the user - `organization_id` string, required: Organization that owns this user - `zone_id` string, required: Zone this user belongs to - `identifier` string, required: Zone-scoped user identifier. Defaults to the user's Keycard ID. When the provider has user_identifier_claim configured, the value is set from that claim at user creation time. - `subject` string: Subject identifier from the identity provider - `issuer` string: Issuer identifier of the identity provider - `email` string, email, required: Email address of the user - `email_verified` boolean, required: Whether the email address has been verified - `status` 'active' | 'disabled', required: Status of the user. Disabled users cannot authenticate. - `external` boolean, required: Whether the user is synced from an external directory over SCIM. When true the user is directory-owned: `status` cannot be changed and the user cannot be deleted through this API while the zone has `external_sync_enabled` set. - `provider_id` string: Reference to the identity provider. This field is undefined when the source identity provider is deleted but the user is not deleted. - `created_at` string, date-time, required: Entity creation timestamp - `updated_at` string, date-time, required: Entity update timestamp - `authenticated_at` string: Date when the user was last authenticated - `session_count` integer: Session count for this user. Populated only when `expand[]=session_count` is set on the listing endpoint. - `grant_count` integer: Delegated-grant count for this user. Populated only when `expand[]=grant_count` is set on the listing endpoint. - `role_assignments` IamUserRoleAssignment[]: Role grants for this user within the zone. Populated only when `expand[]=role-assignments` is set on the listing endpoint. - `role_id` string, required: ID of the assigned role - `role_identifier` string, required: Role identifier: a lowercase slug (letters and digits separated by single hyphens or underscores), unique per owner type within a zone. Role identifiers surface in policy evaluation, so the slug restriction keeps them unambiguous in policy text. - `role_owner_type` 'platform' | 'customer', required: Owner type of the granted role. Disambiguates roles that share an identifier across owner types. - `scope` object, nullable, required: The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself). - `type` string, required: The kind of resource this grant is scoped to (e.g. `zone`). - `id` string, required: The ID of the scoped resource. - `source` 'user' | 'group', required: The principal that holds this grant: `user` when assigned directly to the user, or `group` when inherited through group membership. - `group_id` string: ID of the group this grant is inherited from. Present only when `source` is `group`. - `groups` IamUserGroup[]: Groups this user belongs to within the zone. Populated only when `expand[]=groups` is set on the listing endpoint. - `id` string, required: Unique identifier of the group - `identifier` string, required: Zone-unique slug that policy rules match on. - `name` string, required: Human-readable group name - `external` boolean, required: Whether the group is synced from an external directory. When true the group is directory-owned and its membership is read-only; when false it is managed in Keycard. - `external_issuer` string, nullable, required: Issuer of the external directory the group was synced from. `null` for groups managed in Keycard. Read-only: set by external sync, never by the caller. - `credentials` IamUserCredential[]: Authentication credentials for this user, each carrying its identity provider for federation credentials. Populated only when `expand[]=credentials` is set on the listing endpoint. - union: An authentication credential belonging to a user. - IamUserCredentialFederation: Common fields shared by all user credential types - `created_at` string, date-time, required: Entity creation timestamp - `updated_at` string, date-time, required: Entity update timestamp - `type` 'federation', required - `subject` string: Subject identifier from the identity provider. - `issuer` string: Issuer identifier of the identity provider. - `provider_id` string, nullable, required: ID of the identity provider backing this credential. `null` when the source provider has been deleted. - `provider` IamProvider: A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. - … - IamUserCredentialPassword: Common fields shared by all user credential types - `created_at` string, date-time, required: Entity creation timestamp - `updated_at` string, date-time, required: Entity update timestamp - `type` 'password', required - `provider` IamProvider: A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. - `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 - `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 - `404`: Error response - `default`: Error response ## Changes - **2026-10-16** `0cfaff865771`: 3 warning, 3 info - removed the optional property `items/items/provider/allOf[subschema #1: Provider]/protocols/openid/external_id_claim` from the response with the `200` status - removed the optional property `items/items/resource/allOf[subschema #1: Resource]/credential_provider/allOf[subschema #1: Provider]/protocols/openid/external_id_claim` from the response with the `200` status - removed the optional property `items/items/user/allOf[subschema #1: User]/credentials/items/anyOf[subschema #1: User Credential Federation]/allOf[subschema #2]/provider/allOf[subschema #1: Provider]/protocols/openid/external_id_claim` from the response with the `200` status - added the required property `items/items/user/allOf[subschema #1: User]/external` to the response with the `200` status - …2 more - **2026-08-26** `d65d51379d93`: 11 info - added the non-success response with the status `404` - added the optional property `items/items/provider/allOf[subschema #1: Provider]/metadata/icon_url` to the response with the `200` status - added the optional property `items/items/provider/allOf[subschema #1: Provider]/protocols/openid/external_id_claim` to the response with the `200` status - added the optional property `items/items/resource/allOf[subschema #1: Resource]/credential_provider/allOf[subschema #1: Provider]/metadata/icon_url` to the response with the `200` status - …7 more - …earlier changes not shown [Operation history](https://skmtc.dev/keycardai/apis/untitled-api/changes/zones/:zoneId/delegated-grants/get.md) --- [API](https://skmtc.dev/keycardai/apis/untitled-api.md) - [All operations](https://skmtc.dev/keycardai/apis/untitled-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keycardai/apis/untitled-api/revisions/0dee67e0a73a?raw)