Reference For: developers

API: identity

Operations of the identity tag of the native REST API.

Login, sessions, users, roles, permissions, audit

GET /v1/audit

Audit log, oldest first (requires Global.Diagnostics). With a filter the server reads the log and pages over the matching records; format=csv exports them.

CLI
kyvernon audit list

Parameters

NameInTypeRequiredDescription
limitqueryinteger or nullMaximum items (default 100, maximum 1000; with format=csv up to 100000).
afterquerystring or nullResume after this id (from next).
actorquerystring or nullOnly this actor (user name, exact).
actionquerystring or nullOnly actions that start with this text (identity., identity.user.create).
targetquerystring or nullOnly records about this object id.
outcomequerystring or nullsuccess, denied or error.
sincequerystring or nullOnly records at or after this time (RFC 3339).
untilquerystring or nullOnly records at or before this time (RFC 3339).
qquerystring or nullText that the actor, action, target, correlation id, client address or a detail contains (case-insensitive).
formatquerystring or nulljson (default) or csv (the matching records as a CSV file, no paging).

Responses

StatusDescriptionSchema
200A page of records, or text/csv with format=csvPaged_AuditView

GET /v1/identity/check

Whether the caller holds a privilege on an entity.

CLI
kyvernon privileges check <entity> <privilege>

Parameters

NameInTypeRequiredDescription
entityIdquerystringyesEntity id.
privilegequerystringyesPrivilege id.

Responses

StatusDescriptionSchema
200OKCheckResponse

GET /v1/identity/groups

Lists the local groups (Kyvernon.Identity.ManageUsers).

CLI
kyvernon users groups list

Parameters

NameInTypeRequiredDescription
searchquerystring or nullOnly groups whose name contains this text (case-insensitive).
limitqueryinteger or nullMaximum number of groups (default and maximum 1000).

Responses

StatusDescriptionSchema
200OKarray of GroupView
403Permission denied; args.privilege names the missing privilegeErrorBody

POST /v1/identity/groups

Creates a local group (Kyvernon.Identity.ManageUsers; audited).

CLI
kyvernon users groups create <name>

Request body

application/json: CreateGroupRequest

NameTypeRequiredDescription
descriptionstringDescription.
namestringyesName, 1 to 80 characters.

Responses

StatusDescriptionSchema
201CreatedGroupView
400Invalid argument; the error body names the fieldErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

GET /v1/identity/groups/{name}

Reads one local group with its members (Kyvernon.Identity.ManageUsers).

CLI
kyvernon users groups get <name>

Parameters

NameInTypeRequiredDescription
namepathstringyesName of the local group

Responses

StatusDescriptionSchema
200OKGroupView
404Not found (or not visible to the caller)ErrorBody

PUT /v1/identity/groups/{name}

Renames a group or changes its description (Kyvernon.Identity.ManageUsers; audited). A rename carries the memberships and the permissions of the group.

CLI
kyvernon users groups update <name> --name <new-name>

Parameters

NameInTypeRequiredDescription
namepathstringyesName of the local group

Request body

application/json: UpdateGroupRequest

NameTypeRequiredDescription
descriptionstring or nullNew description.
namestring or nullNew name. Memberships of users and groups and the permissions granted to the group follow the rename.

Responses

StatusDescriptionSchema
200OKGroupView
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody
409Conflict: the object exists, or expectedVersion is staleErrorBody

DELETE /v1/identity/groups/{name}

Deletes a group (Kyvernon.Identity.ManageUsers; audited). Users leave it, it leaves the groups it was nested in, and the permissions granted to it are removed.

CLI
kyvernon users groups delete <name>

Parameters

NameInTypeRequiredDescription
namepathstringyesName of the local group

Responses

StatusDescriptionSchema
204Done; no body
404Not found (or not visible to the caller)ErrorBody

PUT /v1/identity/groups/{name}/members

Replaces the members of a group: exactly these users and nested groups afterwards (Kyvernon.Identity.ManageUsers; audited).

CLI
kyvernon users groups set-members <name> --user <username>

Parameters

NameInTypeRequiredDescription
namepathstringyesName of the local group

Request body

application/json: GroupMembersRequest

NameTypeRequiredDescription
groupsarray of stringGroups to add as nested groups. A group that would contain itself, directly or through other groups, is refused (error.identity.group_cycle).
usersarray of stringUsers to add (local users).

Responses

StatusDescriptionSchema
200OKGroupView
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody

POST /v1/identity/groups/{name}/members

Adds users and nested groups to a group (Kyvernon.Identity.ManageUsers; audited). Members that are already in the group are left as they are.

CLI
kyvernon users groups add <name> --user <username> --group <group>

Parameters

NameInTypeRequiredDescription
namepathstringyesName of the local group

Request body

application/json: GroupMembersRequest

NameTypeRequiredDescription
groupsarray of stringGroups to add as nested groups. A group that would contain itself, directly or through other groups, is refused (error.identity.group_cycle).
usersarray of stringUsers to add (local users).

Responses

StatusDescriptionSchema
200OKGroupView
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody

DELETE /v1/identity/groups/{name}/members/groups/{member}

Removes a nested group from a group (Kyvernon.Identity.ManageUsers; audited).

CLI
kyvernon users groups remove-group <name> <member>

Parameters

NameInTypeRequiredDescription
namepathstringyesName of the local group
memberpathstringyesName of the nested group

Responses

StatusDescriptionSchema
204Done; no body
404Not found (or not visible to the caller)ErrorBody

DELETE /v1/identity/groups/{name}/members/users/{username}

Removes a user from a group (Kyvernon.Identity.ManageUsers; audited).

CLI
kyvernon users groups remove-user <name> <username>

Parameters

NameInTypeRequiredDescription
namepathstringyesName of the local group
usernamepathstringyesUser name of the account

Responses

StatusDescriptionSchema
204Done; no body
404Not found (or not visible to the caller)ErrorBody

GET /v1/identity/lockout-policy

Reads the lockout policy (Kyvernon.Identity.ManagePolicy).

CLI
kyvernon users lockout-policy

Responses

StatusDescriptionSchema
200OKLockoutPolicyView
403Permission denied; args.privilege names the missing privilegeErrorBody

PUT /v1/identity/lockout-policy

Changes the lockout policy (Kyvernon.Identity.ManagePolicy; audited).

CLI
kyvernon users set-lockout-policy --max-failed-attempts <n> --failed-attempt-interval <n> --auto-unlock-interval <n>

Request body

application/json: LockoutPolicyRequest

NameTypeRequiredDescription
autoUnlockIntervalSecondsinteger (int64)yes1 to 604800 seconds (seven days); 0 (the lockout lifted by an administrator only) is refused.
descriptionstring or nullText for administrators (kept when absent).
failedAttemptIntervalSecondsinteger (int64)yes1 to 604800 seconds (seven days).
maxFailedAttemptsinteger (int32)yes1 to 1000.

Responses

StatusDescriptionSchema
200OKLockoutPolicyView
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody

POST /v1/identity/login

Password login.

CLI
kyvernon login <username>

Request body

application/json: LoginRequest

NameTypeRequiredDescription
kindstring or nullinteractive (default) or api.
passwordstringyesPassword.
usernamestringyesUsername.

Responses

StatusDescriptionSchema
200OKLoginResponse
401Not authenticated, or the session is restricted (error.mfa_required, error.password_rotation_required)ErrorBody

POST /v1/identity/logout

Revokes the caller's session.

CLI
kyvernon logout

Responses

StatusDescriptionSchema
204Done; no body

POST /v1/identity/mfa/complete

Completes an MFA login.

CLI
kyvernon login <username> --code <code>

Request body

application/json: CompleteMfaRequest

NameTypeRequiredDescription
codestringyesSix-digit code.
pendingTokenstringyesPending token from the login response.

Responses

StatusDescriptionSchema
200OKSessionView
401Not authenticated, or the session is restricted (error.mfa_required, error.password_rotation_required)ErrorBody

GET /v1/identity/oidc/callback

Completes an OIDC login: starts a browser session family, sets the kyv_refresh and kyvernon_csrf cookies and redirects (303) to the UI at /, which then calls POST /v1/auth/refresh for its access token. No token travels in the body or a URL.

Parameters

NameInTypeRequiredDescription
statequerystringyesState from the start response.
codequerystringyesAuthorization code.

Responses

StatusDescriptionSchema
303Session cookies set; Location: /
401Not authenticated, or the session is restricted (error.mfa_required, error.password_rotation_required)ErrorBody

GET /v1/identity/oidc/config

Reads the identity provider (Global.Settings). The secret is never returned.

CLI
kyvernon users oidc

Responses

StatusDescriptionSchema
200OKOidcAdminView
403Permission denied; args.privilege names the missing privilegeErrorBody

PUT /v1/identity/oidc/config

Sets up the identity provider (Global.Settings; audited). The controller runs provider discovery first; a provider that does not answer is refused (error.identity.oidc_unreachable) and the stored one stays.

CLI
kyvernon users set-oidc --issuer <url> --client-id <id> --client-secret-file <file> --redirect-uri <url>

Request body

application/json: OidcAdminInput

NameTypeRequiredDescription
clientIdstringyesClient id.
clientSecretstring or nullClient secret (write-only). Blank or absent keeps the stored one.
groupsClaimstringClaim with the group names (default groups).
issuerstringyesIssuer URL.
loginTtlSecondsinteger (int64)yesHow long a started sign-in stays valid, 60 to 3600 seconds.
redirectUristringyesRedirect URI, normally https://<controller>/v1/identity/oidc/callback.
scopesarray of stringScopes beyond openid.

Responses

StatusDescriptionSchema
200OKOidcAdminView
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody
412Failed precondition; the error body says whichErrorBody

DELETE /v1/identity/oidc/config

Removes the identity provider (Global.Settings; audited). Local sign-in stays. This also switches off a provider of the [oidc] configuration section.

CLI
kyvernon users remove-oidc

Responses

StatusDescriptionSchema
204Removed
403Permission denied; args.privilege names the missing privilegeErrorBody

GET /v1/identity/oidc/start

Starts an OIDC login; redirect the browser to url. Sets the kyv_oidc cookie (HttpOnly; Secure; SameSite=Lax; Path=/v1/identity/oidc) that binds the login to this browser: the callback refuses a state that arrives without it.

Responses

StatusDescriptionSchema
200Provider URL; sets the kyv_oidc browser-binding cookieOidcStartResponse
501Not configured on this controllerErrorBody

GET /v1/identity/password-policy

Reads the password policy (Kyvernon.Identity.ManagePolicy).

CLI
kyvernon users password-policy

Responses

StatusDescriptionSchema
200OKPasswordPolicyView
403Permission denied; args.privilege names the missing privilegeErrorBody

PUT /v1/identity/password-policy

Changes the password policy (Kyvernon.Identity.ManagePolicy; audited).

CLI
kyvernon users set-password-policy --min-length <n> --max-length <n>

Request body

application/json: PasswordPolicyRequest

NameTypeRequiredDescription
descriptionstring or nullText for administrators (kept when absent).
maxLengthintegeryesLongest password, at most maxLengthCeiling (256) and not below minLength.
minLengthintegeryesShortest password, at least minLengthFloor (12).

Responses

StatusDescriptionSchema
200OKPasswordPolicyView
400Invalid argument; the error body names the fieldErrorBody
403Permission denied; args.privilege names the missing privilegeErrorBody

GET /v1/identity/permissions

Permissions defined on an entity.

CLI
kyvernon permissions list <entity>

Parameters

NameInTypeRequiredDescription
entityIdquerystringyesEntity id.

Responses

StatusDescriptionSchema
200OKarray of PermissionView

PUT /v1/identity/permissions

Sets (creates or replaces) a permission.

CLI
kyvernon permissions set <entity> <principal> --role <role>

Request body

application/json: SetPermissionRequest

NameTypeRequiredDescription
entityIdstringyesEntity id.
principalPrincipalViewyesPrincipal.
propagatebooleanPropagate (default true).
roleIdstringyesRole id.

Responses

StatusDescriptionSchema
200OKPermissionView

DELETE /v1/identity/permissions/{id}

Removes a permission.

CLI
kyvernon permissions remove <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the permission

Responses

StatusDescriptionSchema
204Done; no body

GET /v1/identity/privileges

The privilege catalogue.

CLI
kyvernon privileges list

Responses

StatusDescriptionSchema
200OKarray of PrivilegeView

GET /v1/identity/roles

Lists roles.

CLI
kyvernon roles list

Responses

StatusDescriptionSchema
200OKarray of RoleView

POST /v1/identity/roles

Creates a role.

CLI
kyvernon roles create <name>

Request body

application/json: RoleRequest

NameTypeRequiredDescription
descriptionstringDescription.
namestringyesName.
privilegesarray of stringyesPrivileges from the catalogue.

Responses

StatusDescriptionSchema
201CreatedRoleView

PUT /v1/identity/roles/{id}

Updates a role.

CLI
kyvernon roles update <id> --name <name>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the role

Request body

application/json: RoleRequest

NameTypeRequiredDescription
descriptionstringDescription.
namestringyesName.
privilegesarray of stringyesPrivileges from the catalogue.

Responses

StatusDescriptionSchema
204Done; no body

DELETE /v1/identity/roles/{id}

Deletes a role.

CLI
kyvernon roles delete <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the role

Responses

StatusDescriptionSchema
204Done; no body

GET /v1/identity/self

The caller's identity.

CLI
kyvernon whoami

Responses

StatusDescriptionSchema
200OKWhoAmI

POST /v1/identity/self/mfa/confirm

Confirms TOTP enrolment; returns the ten single-use recovery codes once.

CLI
kyvernon self mfa confirm <code>

Request body

application/json: MfaCodeRequest

NameTypeRequiredDescription
codestringyesSix-digit code.

Responses

StatusDescriptionSchema
200OKRecoveryCodesResponse

POST /v1/identity/self/mfa/enrol

Starts TOTP enrolment for the caller.

CLI
kyvernon self mfa enrol

Responses

StatusDescriptionSchema
200OKMfaEnrolResponse

POST /v1/identity/self/password

Changes the caller's own password. Every other session of the account is revoked; the calling session stays. Browsers use POST /v1/auth/password instead.

CLI
kyvernon self password

Request body

application/json: ChangePasswordRequest

NameTypeRequiredDescription
currentPasswordstring or nullCurrent password (required for self-service).
newPasswordstringyesNew password.

Responses

StatusDescriptionSchema
204Done; no body

GET /v1/identity/sessions

Active sessions (administrator).

CLI
kyvernon sessions list

Responses

StatusDescriptionSchema
200OKarray of SessionInfoView

DELETE /v1/identity/sessions/{id}

Revokes one session (Sessions.TerminateSession; audited). The id is the id of GET /v1/identity/sessions.

CLI
kyvernon sessions revoke <id>

Parameters

NameInTypeRequiredDescription
idpathstringyesId of the session

Responses

StatusDescriptionSchema
204Done; no body
404Not found (or not visible to the caller)ErrorBody

GET /v1/identity/users

Lists users.

CLI
kyvernon users list

Responses

StatusDescriptionSchema
200OKarray of UserView

POST /v1/identity/users

Creates a local user.

CLI
kyvernon users create <username>

Request body

application/json: CreateUserRequest

NameTypeRequiredDescription
displayNamestringDisplay name.
emailstringE-mail.
groupsarray of stringGroups.
passwordstringyesInitial password.
rotationRequiredbooleanRequire a password change at first login (default true).
usernamestringyesUsername.

Responses

StatusDescriptionSchema
201CreatedUserView

GET /v1/identity/users/{username}

One user, with the lockout state (locked, lockedUntil).

CLI
kyvernon users get <username>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Responses

StatusDescriptionSchema
200OKUserView

PUT /v1/identity/users/{username}

Changes a user's display name, e-mail address and local groups (Kyvernon.Identity.ManageUsers; audited as identity.user.update and identity.user.groups).

CLI
kyvernon users update <username> --email <email>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Request body

application/json: UpdateUserRequest

NameTypeRequiredDescription
displayNamestring or nullDisplay name.
emailstring or nullE-mail address.
groupsarray of string or nullThe local groups the user is a direct member of (replaces the set; groups that come from an identity provider stay).

Responses

StatusDescriptionSchema
200OKUserView
400Invalid argument; the error body names the fieldErrorBody
404Not found (or not visible to the caller)ErrorBody

DELETE /v1/identity/users/{username}

Deletes a user.

CLI
kyvernon users delete <username>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Responses

StatusDescriptionSchema
204Done; no body

GET /v1/identity/users/{username}/api-tokens

API tokens of a user (administrator, or the user).

CLI
kyvernon users api-tokens <username> list

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Responses

StatusDescriptionSchema
200OKarray of ApiTokenView

POST /v1/identity/users/{username}/api-tokens

Creates an API token for a user, e.g. a service account (administrator).

CLI
kyvernon users api-tokens <username> create <name>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Request body

application/json: CreateApiTokenRequest

NameTypeRequiredDescription
namestringyesLabel (1..=64 characters).
ttlSecondsinteger (int64) or nullLifetime in seconds, 1 up to the controller maximum ([identity.policy] api_token_max_ttl, 365 days unless configured otherwise). Absent: the maximum. Every token expires; a longer lifetime is refused (error.api_token.ttl).

Responses

StatusDescriptionSchema
201CreatedCreateApiTokenResponse

DELETE /v1/identity/users/{username}/api-tokens/{id}

Revokes an API token of a user (administrator, or the user).

CLI
kyvernon users api-tokens <username> delete <id>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account
idpathstringyesId of the API token

Responses

StatusDescriptionSchema
204Done; no body

PUT /v1/identity/users/{username}/enabled

Enables or disables a user.

CLI
kyvernon users enable <username>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Request body

application/json: SetEnabledRequest

NameTypeRequiredDescription
enabledbooleanyesEnabled.

Responses

StatusDescriptionSchema
204Done; no body

DELETE /v1/identity/users/{username}/mfa

Resets a user's MFA enrolment.

CLI
kyvernon users reset-mfa <username>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Responses

StatusDescriptionSchema
204Done; no body

POST /v1/identity/users/{username}/password

Sets another user's password (administrator).

CLI
kyvernon users set-password <username>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Request body

application/json: ChangePasswordRequest

NameTypeRequiredDescription
currentPasswordstring or nullCurrent password (required for self-service).
newPasswordstringyesNew password.

Responses

StatusDescriptionSchema
204Done; no body

PUT /v1/identity/users/{username}/service-account

Flags or unflags a service account (administrator).

CLI
kyvernon users service-account <username>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Request body

application/json: ServiceAccountRequest

NameTypeRequiredDescription
serviceAccountbooleanyesWhether the account is a service account.

Responses

StatusDescriptionSchema
204Done; no body

DELETE /v1/identity/users/{username}/sessions

Revokes all sessions of a user.

CLI
kyvernon users revoke-sessions <username>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Responses

StatusDescriptionSchema
204Done; no body

POST /v1/identity/users/{username}/unlock

Lifts a lockout (administrator).

CLI
kyvernon users unlock <username>

Parameters

NameInTypeRequiredDescription
usernamepathstringyesUser name of the account

Responses

StatusDescriptionSchema
204Done; no body

Version 0.1.