# Groups ## List `client.Zones.Groups.List(ctx, zoneID, query) (*ZoneGroupListResponse, error)` **get** `/zones/{zoneId}/groups` Returns a paginated list of the groups in the specified zone. Use cursor pagination via `after`/`before`. Sort: comma-separated field list; prefix with `-` for descending (allowed: created_at, name, identifier). Pass `expand[]=member_count` to include each group's member count, `expand[]=roles` to include the identifiers of the roles assigned to each group, and `expand[]=total_count` to include the matching row count. Filter by exact identifier via `filter[identifier]` (repeatable, OR'd across values). Search via `query[]` (case-insensitive substring match, OR'd across repeated values); it matches the group's name and identifier. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of groups — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested group that exists in the zone, in a single page. IDs not in the zone are silently omitted. ### Parameters - `zoneID string` - `query ZoneGroupListParams` - `After param.Field[string]` Cursor for forward pagination - `Before param.Field[string]` Cursor for backward pagination - `Expand param.Field[ZoneGroupListParamsExpandUnion]` - `type ZoneGroupListParamsExpandString string` - `const ZoneGroupListParamsExpandStringTotalCount ZoneGroupListParamsExpandString = "total_count"` - `const ZoneGroupListParamsExpandStringMemberCount ZoneGroupListParamsExpandString = "member_count"` - `const ZoneGroupListParamsExpandStringRoles ZoneGroupListParamsExpandString = "roles"` - `type ZoneGroupListParamsExpandArray []string` - `const ZoneGroupListParamsExpandArrayItemTotalCount ZoneGroupListParamsExpandArrayItem = "total_count"` - `const ZoneGroupListParamsExpandArrayItemMemberCount ZoneGroupListParamsExpandArrayItem = "member_count"` - `const ZoneGroupListParamsExpandArrayItemRoles ZoneGroupListParamsExpandArrayItem = "roles"` - `FilterID param.Field[ZoneGroupListParamsFilterIDUnion]` Restrict results to groups with this ID. Repeatable, max 100. Mutually exclusive with after/before. - `string` - `type ZoneGroupListParamsFilterIDArray []string` - `FilterIdentifier param.Field[ZoneGroupListParamsFilterIdentifierUnion]` Filter by exact group identifier - `string` - `type ZoneGroupListParamsFilterIdentifierArray []string` - `Limit param.Field[int64]` Maximum number of items to return - `Query param.Field[ZoneGroupListParamsQueryUnion]` Search across name and identifier (substring match) - `string` - `type ZoneGroupListParamsQueryArray []string` - `Sort param.Field[string]` Comma-separated sort fields. Prefix with - for descending. Allowed: created_at, name, identifier ### Returns - `type ZoneGroupListResponse struct{…}` - `Items []Group` - `ID string` Unique identifier of the group - `CreatedAt Time` Entity creation timestamp - `External bool` 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. Read-only: set by external sync, never by the caller. - `Identifier string` User-specified identifier, unique within the zone. Automatically assigned for groups from an external directory. - `Name string` Human-readable group name - `OrganizationID string` Organization this group belongs to - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this group belongs to - `MemberCount int64` Number of users in the group. Included only when requested via `expand[]=member_count` (group get or list). - `Roles []string` Identifiers of the roles assigned to the group; members inherit them. Deduped across scopes. Included only when requested via `expand[]=roles` (group get or list). - `Pagination ZoneGroupListResponsePagination` Cursor-based pagination metadata - `AfterCursor string` An opaque cursor used for paginating through a list of results - `BeforeCursor string` An opaque cursor used for paginating through a list of results - `TotalCount int64` Total number of items matching the query. Only included when expand[]=total_count is requested. ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) groups, err := client.Zones.Groups.List( context.TODO(), "zoneId", keycard.ZoneGroupListParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", groups.Items) } ``` ## Create `client.Zones.Groups.New(ctx, zoneID, body) (*Group, error)` **post** `/zones/{zoneId}/groups` Creates a group in the zone (managed in Keycard). Groups synced from an external directory are created by that directory, not here. ### Parameters - `zoneID string` - `body ZoneGroupNewParams` - `GroupCreate param.Field[GroupCreate]` Schema for creating a group in Keycard. Groups synced from an external directory are created by that directory, not through this endpoint. ### Returns - `type Group struct{…}` A zone-scoped group of users, assignable to roles and usable in policies. Roles assigned to a group are inherited by its members. `external` is false for groups managed in Keycard and true for groups synced from an external directory. - `ID string` Unique identifier of the group - `CreatedAt Time` Entity creation timestamp - `External bool` 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. Read-only: set by external sync, never by the caller. - `Identifier string` User-specified identifier, unique within the zone. Automatically assigned for groups from an external directory. - `Name string` Human-readable group name - `OrganizationID string` Organization this group belongs to - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this group belongs to - `MemberCount int64` Number of users in the group. Included only when requested via `expand[]=member_count` (group get or list). - `Roles []string` Identifiers of the roles assigned to the group; members inherit them. Deduped across scopes. Included only when requested via `expand[]=roles` (group get or list). ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) group, err := client.Zones.Groups.New( context.TODO(), "zoneId", keycard.ZoneGroupNewParams{ GroupCreate: keycard.GroupCreateParam{ Name: "x", }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", group.ID) } ``` ## Retrieve `client.Zones.Groups.Get(ctx, groupID, params) (*Group, error)` **get** `/zones/{zoneId}/groups/{groupId}` Returns a group by ID. Pass `expand[]=member_count` for its member count and `expand[]=roles` for the identifiers of its assigned roles. ### Parameters - `groupID string` - `params ZoneGroupGetParams` - `ZoneID param.Field[string]` Path param: Zone ID - `Expand param.Field[ZoneGroupGetParamsExpandUnion]` Query param - `type ZoneGroupGetParamsExpandString string` - `const ZoneGroupGetParamsExpandStringMemberCount ZoneGroupGetParamsExpandString = "member_count"` - `const ZoneGroupGetParamsExpandStringRoles ZoneGroupGetParamsExpandString = "roles"` - `type ZoneGroupGetParamsExpandArray []string` - `const ZoneGroupGetParamsExpandArrayItemMemberCount ZoneGroupGetParamsExpandArrayItem = "member_count"` - `const ZoneGroupGetParamsExpandArrayItemRoles ZoneGroupGetParamsExpandArrayItem = "roles"` ### Returns - `type Group struct{…}` A zone-scoped group of users, assignable to roles and usable in policies. Roles assigned to a group are inherited by its members. `external` is false for groups managed in Keycard and true for groups synced from an external directory. - `ID string` Unique identifier of the group - `CreatedAt Time` Entity creation timestamp - `External bool` 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. Read-only: set by external sync, never by the caller. - `Identifier string` User-specified identifier, unique within the zone. Automatically assigned for groups from an external directory. - `Name string` Human-readable group name - `OrganizationID string` Organization this group belongs to - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this group belongs to - `MemberCount int64` Number of users in the group. Included only when requested via `expand[]=member_count` (group get or list). - `Roles []string` Identifiers of the roles assigned to the group; members inherit them. Deduped across scopes. Included only when requested via `expand[]=roles` (group get or list). ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) group, err := client.Zones.Groups.Get( context.TODO(), "groupId", keycard.ZoneGroupGetParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", group.ID) } ``` ## Update `client.Zones.Groups.Update(ctx, groupID, params) (*Group, error)` **patch** `/zones/{zoneId}/groups/{groupId}` Updates a group's name and/or identifier (partial update). A group's source is immutable. The name of a group synced from an external directory cannot be changed while external sync is enabled for the zone; its identifier can. ### Parameters - `groupID string` - `params ZoneGroupUpdateParams` - `ZoneID param.Field[string]` Path param: Zone ID - `GroupUpdate param.Field[GroupUpdate]` Body param: Schema for updating a group. ### Returns - `type Group struct{…}` A zone-scoped group of users, assignable to roles and usable in policies. Roles assigned to a group are inherited by its members. `external` is false for groups managed in Keycard and true for groups synced from an external directory. - `ID string` Unique identifier of the group - `CreatedAt Time` Entity creation timestamp - `External bool` 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. Read-only: set by external sync, never by the caller. - `Identifier string` User-specified identifier, unique within the zone. Automatically assigned for groups from an external directory. - `Name string` Human-readable group name - `OrganizationID string` Organization this group belongs to - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this group belongs to - `MemberCount int64` Number of users in the group. Included only when requested via `expand[]=member_count` (group get or list). - `Roles []string` Identifiers of the roles assigned to the group; members inherit them. Deduped across scopes. Included only when requested via `expand[]=roles` (group get or list). ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) group, err := client.Zones.Groups.Update( context.TODO(), "groupId", keycard.ZoneGroupUpdateParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", group.ID) } ``` ## Delete `client.Zones.Groups.Delete(ctx, groupID, body) error` **delete** `/zones/{zoneId}/groups/{groupId}` Deletes a group and its memberships and role assignments. Groups synced from an external directory can only be deleted by that directory (after external sync is disabled). ### Parameters - `groupID string` - `body ZoneGroupDeleteParams` - `ZoneID param.Field[string]` Zone ID ### Example ```go package main import ( "context" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) err := client.Zones.Groups.Delete( context.TODO(), "groupId", keycard.ZoneGroupDeleteParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } } ``` ## Domain Types ### Group - `type Group struct{…}` A zone-scoped group of users, assignable to roles and usable in policies. Roles assigned to a group are inherited by its members. `external` is false for groups managed in Keycard and true for groups synced from an external directory. - `ID string` Unique identifier of the group - `CreatedAt Time` Entity creation timestamp - `External bool` 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. Read-only: set by external sync, never by the caller. - `Identifier string` User-specified identifier, unique within the zone. Automatically assigned for groups from an external directory. - `Name string` Human-readable group name - `OrganizationID string` Organization this group belongs to - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this group belongs to - `MemberCount int64` Number of users in the group. Included only when requested via `expand[]=member_count` (group get or list). - `Roles []string` Identifiers of the roles assigned to the group; members inherit them. Deduped across scopes. Included only when requested via `expand[]=roles` (group get or list). ### Group Create - `type GroupCreate struct{…}` Schema for creating a group in Keycard. Groups synced from an external directory are created by that directory, not through this endpoint. - `Name string` Human-readable group name - `Identifier string` User-specified identifier, unique within the zone. Derived from the name when omitted (a suffix is appended if it collides). ### Group Update - `type GroupUpdate struct{…}` Schema for updating a group. - `Identifier string` User-specified identifier, unique within the zone. - `Name string` Human-readable group name # Members ## List `client.Zones.Groups.Members.List(ctx, groupID, params) (*ZoneGroupMemberListResponse, error)` **get** `/zones/{zoneId}/groups/{groupId}/members` Returns a paginated list of the group's members. Use cursor pagination via `after`/`before`. Pass `expand[]=user` to embed each member's full user record and `expand[]=total_count` to include the matching row count. Pass `query[]` (repeatable, 1-255 chars) to search members by their user's email or federated credential subject (substring match, OR'd across repeated values). Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of members by user ID — mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested member that exists in the group, in a single page. IDs not in the group are silently omitted. ### Parameters - `groupID string` - `params ZoneGroupMemberListParams` - `ZoneID param.Field[string]` Path param: Zone ID - `After param.Field[string]` Query param: Cursor for forward pagination - `Before param.Field[string]` Query param: Cursor for backward pagination - `Expand param.Field[ZoneGroupMemberListParamsExpandUnion]` Query param - `type ZoneGroupMemberListParamsExpandString string` - `const ZoneGroupMemberListParamsExpandStringTotalCount ZoneGroupMemberListParamsExpandString = "total_count"` - `const ZoneGroupMemberListParamsExpandStringUser ZoneGroupMemberListParamsExpandString = "user"` - `type ZoneGroupMemberListParamsExpandArray []string` - `const ZoneGroupMemberListParamsExpandArrayItemTotalCount ZoneGroupMemberListParamsExpandArrayItem = "total_count"` - `const ZoneGroupMemberListParamsExpandArrayItemUser ZoneGroupMemberListParamsExpandArrayItem = "user"` - `FilterID param.Field[ZoneGroupMemberListParamsFilterIDUnion]` Query param: Restrict results to the member with this user ID. Repeatable, max 100. Mutually exclusive with after/before. - `string` - `type ZoneGroupMemberListParamsFilterIDArray []string` - `Limit param.Field[int64]` Query param: Maximum number of items to return - `Query param.Field[ZoneGroupMemberListParamsQueryUnion]` Query param: Search members by their user's email or federated credential subject (substring match) - `string` - `type ZoneGroupMemberListParamsQueryArray []string` ### Returns - `type ZoneGroupMemberListResponse struct{…}` - `Items []GroupMember` - `CreatedAt Time` Entity creation timestamp - `UserID string` ID of the user - `User User` An authenticated user entity - `ID string` Unique identifier of the user - `CreatedAt Time` Entity creation timestamp - `Email string` Email address of the user - `EmailVerified bool` Whether the email address has been verified - `Identifier string` 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. - `OrganizationID string` Organization that owns this user - `Status UserStatus` Status of the user. Disabled users cannot authenticate. - `const UserStatusActive UserStatus = "active"` - `const UserStatusDisabled UserStatus = "disabled"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this user belongs to - `AuthenticatedAt string` Date when the user was last authenticated - `Credentials []UserCredentialUnion` Authentication credentials for this user, each carrying its identity provider for federation credentials. Populated only when `expand[]=credentials` is set on the listing endpoint. - `type UserCredentialUserCredentialFederation struct{…}` Federation credential: the user authenticates through an identity provider. - `CreatedAt Time` Entity creation timestamp - `ProviderID string` ID of the identity provider backing this credential. `null` when the source provider has been deleted. - `Type string` - `const UserCredentialUserCredentialFederationTypeFederation UserCredentialUserCredentialFederationType = "federation"` - `UpdatedAt Time` Entity update timestamp - `Issuer string` Issuer identifier of the identity provider. - `Provider Provider` A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. - `ID string` Unique identifier of the provider - `CreatedAt Time` Entity creation timestamp - `Identifier string` User specified identifier, unique within the zone - `Name string` Human-readable name - `OrganizationID string` Organization that owns this provider - `OwnerType ProviderOwnerType` Who owns this provider. Platform-owned providers cannot be modified via API. - `const ProviderOwnerTypePlatform ProviderOwnerType = "platform"` - `const ProviderOwnerTypeCustomer ProviderOwnerType = "customer"` - `Slug string` URL-safe identifier, unique within the zone - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this provider belongs to - `ClientID string` OAuth 2.0 client identifier - `ClientSecretSet bool` Indicates whether a client secret is configured - `Description string` Human-readable description - `Metadata ProviderMetadata` Provider metadata - `IconURL string` Icon URL - `Protocols ProviderProtocols` Protocol-specific configuration - `Oauth2 ProviderProtocolsOauth2` OAuth 2.0 protocol configuration - `Issuer string` OIDC issuer URL used for discovery and token validation. - `AuthorizationEndpoint string` - `AuthorizationParameters map[string, string]` Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline). - `AuthorizationResourceEnabled bool` Whether to include the resource parameter in authorization requests. - `AuthorizationResourceParameter string` The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true. - `CodeChallengeMethodsSupported []string` - `JwksUri string` - `RegistrationEndpoint string` - `ScopeParameter string` The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope". - `ScopeSeparator string` The separator character for scope values. Defaults to " " (space). Slack v2 uses ",". - `ScopesSupported []string` - `TokenEndpoint string` - `TokenResponseAccessTokenPointer string` Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token". - `Openid ProviderProtocolsOpenid` OpenID Connect protocol configuration - `ExternalIDClaim string` Name of the OIDC claim carrying the stable external id used to correlate logins with externally provisioned (SCIM) users. Defaults to "sub". Set to "oid" for Entra, whose pairwise "sub" differs from the SCIM externalId. - `Scopes []string` Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email). - `SingleLogoutEnabled bool` When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false. - `UserIdentifierClaim string` 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. - `UserinfoEndpoint string` - `Type ProviderType` - `const ProviderTypeExternal ProviderType = "external"` - `const ProviderTypeKeycardVault ProviderType = "keycard-vault"` - `const ProviderTypeKeycardSts ProviderType = "keycard-sts"` - `Subject string` Subject identifier from the identity provider. - `type UserCredentialUserCredentialPassword struct{…}` Password credential: the user authenticates with email and password. The email lives on the user. - `CreatedAt Time` Entity creation timestamp - `Type string` - `const UserCredentialUserCredentialPasswordTypePassword UserCredentialUserCredentialPasswordType = "password"` - `UpdatedAt Time` Entity update timestamp - `GrantCount int64` Delegated-grant count for this user. Populated only when `expand[]=grant_count` is set on the listing endpoint. - `Groups []UserGroup` Groups this user belongs to within the zone. Populated only when `expand[]=groups` is set on the listing endpoint. - `ID string` Unique identifier of the group - `Identifier string` Zone-unique slug that policy rules match on. - `Name string` Human-readable group name - `Issuer string` Issuer identifier of the identity provider - `ProviderID string` Reference to the identity provider. This field is undefined when the source identity provider is deleted but the user is not deleted. - `RoleAssignments []UserRoleAssignment` Role grants for this user within the zone. Populated only when `expand[]=role-assignments` is set on the listing endpoint. - `RoleID string` ID of the assigned role - `RoleIdentifier string` 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. - `RoleOwnerType string` Owner type of the granted role. Disambiguates roles that share an identifier across owner types. - `const UserRoleAssignmentRoleOwnerTypePlatform UserRoleAssignmentRoleOwnerType = "platform"` - `const UserRoleAssignmentRoleOwnerTypeCustomer UserRoleAssignmentRoleOwnerType = "customer"` - `Scope UserRoleAssignmentScope` The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself). - `ID string` The ID of the scoped resource. - `Type string` The kind of resource this grant is scoped to (e.g. `zone`). - `Source string` The principal that holds this grant: `user` when assigned directly to the user, or `group` when inherited through group membership. - `const UserRoleAssignmentSourceUser UserRoleAssignmentSource = "user"` - `const UserRoleAssignmentSourceGroup UserRoleAssignmentSource = "group"` - `GroupID string` ID of the group this grant is inherited from. Present only when `source` is `group`. - `SessionCount int64` Session count for this user. Populated only when `expand[]=session_count` is set on the listing endpoint. - `Subject string` Subject identifier from the identity provider - `Pagination ZoneGroupMemberListResponsePagination` Cursor-based pagination metadata - `AfterCursor string` An opaque cursor used for paginating through a list of results - `BeforeCursor string` An opaque cursor used for paginating through a list of results - `TotalCount int64` Total number of items matching the query. Only included when expand[]=total_count is requested. ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) members, err := client.Zones.Groups.Members.List( context.TODO(), "groupId", keycard.ZoneGroupMemberListParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", members.Items) } ``` ## Add `client.Zones.Groups.Members.Add(ctx, groupID, params) (*GroupMember, error)` **post** `/zones/{zoneId}/groups/{groupId}/members` Adds a user to a group managed in Keycard. Membership of externally synced groups is not managed manually. ### Parameters - `groupID string` - `params ZoneGroupMemberAddParams` - `ZoneID param.Field[string]` Path param: Zone ID - `GroupMemberCreate param.Field[GroupMemberCreate]` Body param: Schema for adding a user to a group ### Returns - `type GroupMember struct{…}` A user's membership in a group - `CreatedAt Time` Entity creation timestamp - `UserID string` ID of the user - `User User` An authenticated user entity - `ID string` Unique identifier of the user - `CreatedAt Time` Entity creation timestamp - `Email string` Email address of the user - `EmailVerified bool` Whether the email address has been verified - `Identifier string` 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. - `OrganizationID string` Organization that owns this user - `Status UserStatus` Status of the user. Disabled users cannot authenticate. - `const UserStatusActive UserStatus = "active"` - `const UserStatusDisabled UserStatus = "disabled"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this user belongs to - `AuthenticatedAt string` Date when the user was last authenticated - `Credentials []UserCredentialUnion` Authentication credentials for this user, each carrying its identity provider for federation credentials. Populated only when `expand[]=credentials` is set on the listing endpoint. - `type UserCredentialUserCredentialFederation struct{…}` Federation credential: the user authenticates through an identity provider. - `CreatedAt Time` Entity creation timestamp - `ProviderID string` ID of the identity provider backing this credential. `null` when the source provider has been deleted. - `Type string` - `const UserCredentialUserCredentialFederationTypeFederation UserCredentialUserCredentialFederationType = "federation"` - `UpdatedAt Time` Entity update timestamp - `Issuer string` Issuer identifier of the identity provider. - `Provider Provider` A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. - `ID string` Unique identifier of the provider - `CreatedAt Time` Entity creation timestamp - `Identifier string` User specified identifier, unique within the zone - `Name string` Human-readable name - `OrganizationID string` Organization that owns this provider - `OwnerType ProviderOwnerType` Who owns this provider. Platform-owned providers cannot be modified via API. - `const ProviderOwnerTypePlatform ProviderOwnerType = "platform"` - `const ProviderOwnerTypeCustomer ProviderOwnerType = "customer"` - `Slug string` URL-safe identifier, unique within the zone - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this provider belongs to - `ClientID string` OAuth 2.0 client identifier - `ClientSecretSet bool` Indicates whether a client secret is configured - `Description string` Human-readable description - `Metadata ProviderMetadata` Provider metadata - `IconURL string` Icon URL - `Protocols ProviderProtocols` Protocol-specific configuration - `Oauth2 ProviderProtocolsOauth2` OAuth 2.0 protocol configuration - `Issuer string` OIDC issuer URL used for discovery and token validation. - `AuthorizationEndpoint string` - `AuthorizationParameters map[string, string]` Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline). - `AuthorizationResourceEnabled bool` Whether to include the resource parameter in authorization requests. - `AuthorizationResourceParameter string` The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true. - `CodeChallengeMethodsSupported []string` - `JwksUri string` - `RegistrationEndpoint string` - `ScopeParameter string` The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope". - `ScopeSeparator string` The separator character for scope values. Defaults to " " (space). Slack v2 uses ",". - `ScopesSupported []string` - `TokenEndpoint string` - `TokenResponseAccessTokenPointer string` Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token". - `Openid ProviderProtocolsOpenid` OpenID Connect protocol configuration - `ExternalIDClaim string` Name of the OIDC claim carrying the stable external id used to correlate logins with externally provisioned (SCIM) users. Defaults to "sub". Set to "oid" for Entra, whose pairwise "sub" differs from the SCIM externalId. - `Scopes []string` Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email). - `SingleLogoutEnabled bool` When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false. - `UserIdentifierClaim string` 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. - `UserinfoEndpoint string` - `Type ProviderType` - `const ProviderTypeExternal ProviderType = "external"` - `const ProviderTypeKeycardVault ProviderType = "keycard-vault"` - `const ProviderTypeKeycardSts ProviderType = "keycard-sts"` - `Subject string` Subject identifier from the identity provider. - `type UserCredentialUserCredentialPassword struct{…}` Password credential: the user authenticates with email and password. The email lives on the user. - `CreatedAt Time` Entity creation timestamp - `Type string` - `const UserCredentialUserCredentialPasswordTypePassword UserCredentialUserCredentialPasswordType = "password"` - `UpdatedAt Time` Entity update timestamp - `GrantCount int64` Delegated-grant count for this user. Populated only when `expand[]=grant_count` is set on the listing endpoint. - `Groups []UserGroup` Groups this user belongs to within the zone. Populated only when `expand[]=groups` is set on the listing endpoint. - `ID string` Unique identifier of the group - `Identifier string` Zone-unique slug that policy rules match on. - `Name string` Human-readable group name - `Issuer string` Issuer identifier of the identity provider - `ProviderID string` Reference to the identity provider. This field is undefined when the source identity provider is deleted but the user is not deleted. - `RoleAssignments []UserRoleAssignment` Role grants for this user within the zone. Populated only when `expand[]=role-assignments` is set on the listing endpoint. - `RoleID string` ID of the assigned role - `RoleIdentifier string` 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. - `RoleOwnerType string` Owner type of the granted role. Disambiguates roles that share an identifier across owner types. - `const UserRoleAssignmentRoleOwnerTypePlatform UserRoleAssignmentRoleOwnerType = "platform"` - `const UserRoleAssignmentRoleOwnerTypeCustomer UserRoleAssignmentRoleOwnerType = "customer"` - `Scope UserRoleAssignmentScope` The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself). - `ID string` The ID of the scoped resource. - `Type string` The kind of resource this grant is scoped to (e.g. `zone`). - `Source string` The principal that holds this grant: `user` when assigned directly to the user, or `group` when inherited through group membership. - `const UserRoleAssignmentSourceUser UserRoleAssignmentSource = "user"` - `const UserRoleAssignmentSourceGroup UserRoleAssignmentSource = "group"` - `GroupID string` ID of the group this grant is inherited from. Present only when `source` is `group`. - `SessionCount int64` Session count for this user. Populated only when `expand[]=session_count` is set on the listing endpoint. - `Subject string` Subject identifier from the identity provider ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) groupMember, err := client.Zones.Groups.Members.Add( context.TODO(), "groupId", keycard.ZoneGroupMemberAddParams{ ZoneID: "zoneId", GroupMemberCreate: keycard.GroupMemberCreateParam{ UserID: "user_id", }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", groupMember.UserID) } ``` ## Remove `client.Zones.Groups.Members.Remove(ctx, userID, body) error` **delete** `/zones/{zoneId}/groups/{groupId}/members/{userId}` Removes a user from a group managed in Keycard. Membership of externally synced groups is not managed manually. A member is identified by its user's ID. ### Parameters - `userID string` - `body ZoneGroupMemberRemoveParams` - `ZoneID param.Field[string]` Zone ID - `GroupID param.Field[string]` Group ID ### Example ```go package main import ( "context" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) err := client.Zones.Groups.Members.Remove( context.TODO(), "userId", keycard.ZoneGroupMemberRemoveParams{ ZoneID: "zoneId", GroupID: "groupId", }, ) if err != nil { panic(err.Error()) } } ``` ## Domain Types ### Group Member - `type GroupMember struct{…}` A user's membership in a group - `CreatedAt Time` Entity creation timestamp - `UserID string` ID of the user - `User User` An authenticated user entity - `ID string` Unique identifier of the user - `CreatedAt Time` Entity creation timestamp - `Email string` Email address of the user - `EmailVerified bool` Whether the email address has been verified - `Identifier string` 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. - `OrganizationID string` Organization that owns this user - `Status UserStatus` Status of the user. Disabled users cannot authenticate. - `const UserStatusActive UserStatus = "active"` - `const UserStatusDisabled UserStatus = "disabled"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this user belongs to - `AuthenticatedAt string` Date when the user was last authenticated - `Credentials []UserCredentialUnion` Authentication credentials for this user, each carrying its identity provider for federation credentials. Populated only when `expand[]=credentials` is set on the listing endpoint. - `type UserCredentialUserCredentialFederation struct{…}` Federation credential: the user authenticates through an identity provider. - `CreatedAt Time` Entity creation timestamp - `ProviderID string` ID of the identity provider backing this credential. `null` when the source provider has been deleted. - `Type string` - `const UserCredentialUserCredentialFederationTypeFederation UserCredentialUserCredentialFederationType = "federation"` - `UpdatedAt Time` Entity update timestamp - `Issuer string` Issuer identifier of the identity provider. - `Provider Provider` A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate. - `ID string` Unique identifier of the provider - `CreatedAt Time` Entity creation timestamp - `Identifier string` User specified identifier, unique within the zone - `Name string` Human-readable name - `OrganizationID string` Organization that owns this provider - `OwnerType ProviderOwnerType` Who owns this provider. Platform-owned providers cannot be modified via API. - `const ProviderOwnerTypePlatform ProviderOwnerType = "platform"` - `const ProviderOwnerTypeCustomer ProviderOwnerType = "customer"` - `Slug string` URL-safe identifier, unique within the zone - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this provider belongs to - `ClientID string` OAuth 2.0 client identifier - `ClientSecretSet bool` Indicates whether a client secret is configured - `Description string` Human-readable description - `Metadata ProviderMetadata` Provider metadata - `IconURL string` Icon URL - `Protocols ProviderProtocols` Protocol-specific configuration - `Oauth2 ProviderProtocolsOauth2` OAuth 2.0 protocol configuration - `Issuer string` OIDC issuer URL used for discovery and token validation. - `AuthorizationEndpoint string` - `AuthorizationParameters map[string, string]` Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline). - `AuthorizationResourceEnabled bool` Whether to include the resource parameter in authorization requests. - `AuthorizationResourceParameter string` The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true. - `CodeChallengeMethodsSupported []string` - `JwksUri string` - `RegistrationEndpoint string` - `ScopeParameter string` The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope". - `ScopeSeparator string` The separator character for scope values. Defaults to " " (space). Slack v2 uses ",". - `ScopesSupported []string` - `TokenEndpoint string` - `TokenResponseAccessTokenPointer string` Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token". - `Openid ProviderProtocolsOpenid` OpenID Connect protocol configuration - `ExternalIDClaim string` Name of the OIDC claim carrying the stable external id used to correlate logins with externally provisioned (SCIM) users. Defaults to "sub". Set to "oid" for Entra, whose pairwise "sub" differs from the SCIM externalId. - `Scopes []string` Additional OIDC scopes to request from this provider during authentication (e.g. "groups"). Merged with the default scopes (openid, profile, email). - `SingleLogoutEnabled bool` When true, logging out of the zone propagates the logout to this provider's end_session_endpoint (RP-initiated logout). Defaults to false. - `UserIdentifierClaim string` 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. - `UserinfoEndpoint string` - `Type ProviderType` - `const ProviderTypeExternal ProviderType = "external"` - `const ProviderTypeKeycardVault ProviderType = "keycard-vault"` - `const ProviderTypeKeycardSts ProviderType = "keycard-sts"` - `Subject string` Subject identifier from the identity provider. - `type UserCredentialUserCredentialPassword struct{…}` Password credential: the user authenticates with email and password. The email lives on the user. - `CreatedAt Time` Entity creation timestamp - `Type string` - `const UserCredentialUserCredentialPasswordTypePassword UserCredentialUserCredentialPasswordType = "password"` - `UpdatedAt Time` Entity update timestamp - `GrantCount int64` Delegated-grant count for this user. Populated only when `expand[]=grant_count` is set on the listing endpoint. - `Groups []UserGroup` Groups this user belongs to within the zone. Populated only when `expand[]=groups` is set on the listing endpoint. - `ID string` Unique identifier of the group - `Identifier string` Zone-unique slug that policy rules match on. - `Name string` Human-readable group name - `Issuer string` Issuer identifier of the identity provider - `ProviderID string` Reference to the identity provider. This field is undefined when the source identity provider is deleted but the user is not deleted. - `RoleAssignments []UserRoleAssignment` Role grants for this user within the zone. Populated only when `expand[]=role-assignments` is set on the listing endpoint. - `RoleID string` ID of the assigned role - `RoleIdentifier string` 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. - `RoleOwnerType string` Owner type of the granted role. Disambiguates roles that share an identifier across owner types. - `const UserRoleAssignmentRoleOwnerTypePlatform UserRoleAssignmentRoleOwnerType = "platform"` - `const UserRoleAssignmentRoleOwnerTypeCustomer UserRoleAssignmentRoleOwnerType = "customer"` - `Scope UserRoleAssignmentScope` The resource this grant is scoped to, or null when the grant is unscoped (applies to the owning zone itself). - `ID string` The ID of the scoped resource. - `Type string` The kind of resource this grant is scoped to (e.g. `zone`). - `Source string` The principal that holds this grant: `user` when assigned directly to the user, or `group` when inherited through group membership. - `const UserRoleAssignmentSourceUser UserRoleAssignmentSource = "user"` - `const UserRoleAssignmentSourceGroup UserRoleAssignmentSource = "group"` - `GroupID string` ID of the group this grant is inherited from. Present only when `source` is `group`. - `SessionCount int64` Session count for this user. Populated only when `expand[]=session_count` is set on the listing endpoint. - `Subject string` Subject identifier from the identity provider ### Group Member Create - `type GroupMemberCreate struct{…}` Schema for adding a user to a group - `UserID string` ID of the user to add to the group # Roles ## List `client.Zones.Groups.Roles.List(ctx, groupID, params) (*ZoneGroupRoleListResponse, error)` **get** `/zones/{zoneId}/groups/{groupId}/roles` Returns the roles assigned to the group. Members inherit these roles. Returns the shared role-assignment shape with `principal_type` set to `group`. Use cursor pagination via `after`/`before`; pass `expand[]=total_count` to include the matching row count. Pass `filter[id]` (repeatable, max 100) to restrict results to a known set of role assignments, mutually exclusive with `after`/`before` (returns 400 if combined). When `filter[id]` is set, `limit` is ignored and the response contains every requested assignment that exists on the group, in a single page. IDs not on the group are silently omitted. ### Parameters - `groupID string` - `params ZoneGroupRoleListParams` - `ZoneID param.Field[string]` Path param: Zone ID - `After param.Field[string]` Query param: Cursor for forward pagination - `Before param.Field[string]` Query param: Cursor for backward pagination - `Expand param.Field[ZoneGroupRoleListParamsExpandUnion]` Query param - `type ZoneGroupRoleListParamsExpandString string` - `const ZoneGroupRoleListParamsExpandStringTotalCount ZoneGroupRoleListParamsExpandString = "total_count"` - `type ZoneGroupRoleListParamsExpandArray []string` - `const ZoneGroupRoleListParamsExpandArrayItemTotalCount ZoneGroupRoleListParamsExpandArrayItem = "total_count"` - `FilterID param.Field[ZoneGroupRoleListParamsFilterIDUnion]` Query param: Restrict results to the role assignment with this ID. Repeatable, max 100. Mutually exclusive with after/before. - `string` - `type ZoneGroupRoleListParamsFilterIDArray []string` - `Limit param.Field[int64]` Query param: Maximum number of items to return ### Returns - `type ZoneGroupRoleListResponse struct{…}` - `Items []RoleAssignment` - `ID string` Unique identifier of the role assignment - `CreatedAt Time` Entity creation timestamp - `PrincipalID string` ID of the principal the role is assigned to (a user, application, or group ID). - `PrincipalType string` The kind of principal the role is assigned to: `user`, `application`, or `group`. A role assigned to a `group` is inherited by that group's members. - `RoleID string` ID of the assigned role - `RoleIdentifier string` 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. - `RoleOwnerType RoleAssignmentRoleOwnerType` Owner type of the assigned role. Disambiguates roles that share an identifier across owner types. - `const RoleAssignmentRoleOwnerTypePlatform RoleAssignmentRoleOwnerType = "platform"` - `const RoleAssignmentRoleOwnerTypeCustomer RoleAssignmentRoleOwnerType = "customer"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this assignment belongs to - `ScopeID string` The ID of the scoped resource. Null when the assignment is unscoped. - `ScopeType string` The kind of resource this grant is scoped to (e.g. `zone`). Null when the assignment is unscoped (applies to the owning zone itself). - `Pagination ZoneGroupRoleListResponsePagination` Cursor-based pagination metadata - `AfterCursor string` An opaque cursor used for paginating through a list of results - `BeforeCursor string` An opaque cursor used for paginating through a list of results - `TotalCount int64` Total number of items matching the query. Only included when expand[]=total_count is requested. ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) roles, err := client.Zones.Groups.Roles.List( context.TODO(), "groupId", keycard.ZoneGroupRoleListParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", roles.Items) } ``` ## Add `client.Zones.Groups.Roles.Add(ctx, groupID, params) (*RoleAssignment, error)` **post** `/zones/{zoneId}/groups/{groupId}/roles` Assigns a role to the group; members inherit it. Provide role_id, or role_identifier with owner_type. Returns the shared role-assignment shape with `principal_type` set to `group`. ### Parameters - `groupID string` - `params ZoneGroupRoleAddParams` - `ZoneID param.Field[string]` Path param: Zone ID - `RoleAssignmentCreate param.Field[RoleAssignmentCreate]` Body param: Schema for assigning a role to a principal. Provide exactly one of role_id or role_identifier. When role_identifier is used, owner_type is required to disambiguate roles that share an identifier across owner types; owner_type must be omitted when role_id is used. ### Returns - `type RoleAssignment struct{…}` Represents a role assigned to a principal within a zone - `ID string` Unique identifier of the role assignment - `CreatedAt Time` Entity creation timestamp - `PrincipalID string` ID of the principal the role is assigned to (a user, application, or group ID). - `PrincipalType string` The kind of principal the role is assigned to: `user`, `application`, or `group`. A role assigned to a `group` is inherited by that group's members. - `RoleID string` ID of the assigned role - `RoleIdentifier string` 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. - `RoleOwnerType RoleAssignmentRoleOwnerType` Owner type of the assigned role. Disambiguates roles that share an identifier across owner types. - `const RoleAssignmentRoleOwnerTypePlatform RoleAssignmentRoleOwnerType = "platform"` - `const RoleAssignmentRoleOwnerTypeCustomer RoleAssignmentRoleOwnerType = "customer"` - `UpdatedAt Time` Entity update timestamp - `ZoneID string` Zone this assignment belongs to - `ScopeID string` The ID of the scoped resource. Null when the assignment is unscoped. - `ScopeType string` The kind of resource this grant is scoped to (e.g. `zone`). Null when the assignment is unscoped (applies to the owning zone itself). ### Example ```go package main import ( "context" "fmt" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) roleAssignment, err := client.Zones.Groups.Roles.Add( context.TODO(), "groupId", keycard.ZoneGroupRoleAddParams{ ZoneID: "zoneId", }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", roleAssignment.ID) } ``` ## Remove `client.Zones.Groups.Roles.Remove(ctx, roleID, params) error` **delete** `/zones/{zoneId}/groups/{groupId}/roles/{roleId}` Revokes a role from the group. Provide the same (scope_type, scope_id) pair the grant was created with, or omit both to revoke the unscoped grant. ### Parameters - `roleID string` - `params ZoneGroupRoleRemoveParams` - `ZoneID param.Field[string]` Path param: Zone ID - `GroupID param.Field[string]` Path param: Group ID - `ScopeID param.Field[string]` Query param: Scope target of the grant to revoke. Provide together with scope_type. - `ScopeType param.Field[string]` Query param: Scope kind of the grant to revoke. Provide together with scope_id. ### Example ```go package main import ( "context" "github.com/keycardai/keycard-go" "github.com/keycardai/keycard-go/option" ) func main() { client := keycard.NewClient( option.WithAPIKey("My API Key"), ) err := client.Zones.Groups.Roles.Remove( context.TODO(), "roleId", keycard.ZoneGroupRoleRemoveParams{ ZoneID: "zoneId", GroupID: "groupId", }, ) if err != nil { panic(err.Error()) } } ```