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
| Name | In | Type | Required | Description |
|---|
limit | query | integer or null | | Maximum items (default 100, maximum 1000; with format=csv up to 100000). |
|---|
after | query | string or null | | Resume after this id (from next). |
|---|
actor | query | string or null | | Only this actor (user name, exact). |
|---|
action | query | string or null | | Only actions that start with this text (identity., identity.user.create). |
|---|
target | query | string or null | | Only records about this object id. |
|---|
outcome | query | string or null | | success, denied or error. |
|---|
since | query | string or null | | Only records at or after this time (RFC 3339). |
|---|
until | query | string or null | | Only records at or before this time (RFC 3339). |
|---|
q | query | string or null | | Text that the actor, action, target, correlation id, client address or a detail contains (case-insensitive). |
|---|
format | query | string or null | | json (default) or csv (the matching records as a CSV file, no paging). |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | A page of records, or text/csv with format=csv | Paged_AuditView |
|---|
GET /v1/identity/check
Whether the caller holds a privilege on an entity.
- CLI
kyvernon privileges check <entity> <privilege>
Parameters
| Name | In | Type | Required | Description |
|---|
entityId | query | string | yes | Entity id. |
|---|
privilege | query | string | yes | Privilege id. |
|---|
Responses
GET /v1/identity/groups
Lists the local groups (Kyvernon.Identity.ManageUsers).
- CLI
kyvernon users groups list
Parameters
| Name | In | Type | Required | Description |
|---|
search | query | string or null | | Only groups whose name contains this text (case-insensitive). |
|---|
limit | query | integer or null | | Maximum number of groups (default and maximum 1000). |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | array of GroupView |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
POST /v1/identity/groups
Creates a local group (Kyvernon.Identity.ManageUsers; audited).
- CLI
kyvernon users groups create <name>
Request body
application/json: CreateGroupRequest
| Name | Type | Required | Description |
|---|
description | string | | Description. |
|---|
name | string | yes | Name, 1 to 80 characters. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | GroupView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
GET /v1/identity/groups/{name}
Reads one local group with its members (Kyvernon.Identity.ManageUsers).
- CLI
kyvernon users groups get <name>
Parameters
| Name | In | Type | Required | Description |
|---|
name | path | string | yes | Name of the local group |
|---|
Responses
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
| Name | In | Type | Required | Description |
|---|
name | path | string | yes | Name of the local group |
|---|
Request body
application/json: UpdateGroupRequest
| Name | Type | Required | Description |
|---|
description | string or null | | New description. |
|---|
name | string or null | | New name. Memberships of users and groups and the permissions granted to the group follow the rename. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | GroupView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
| 409 | Conflict: the object exists, or expectedVersion is stale | ErrorBody |
|---|
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
| Name | In | Type | Required | Description |
|---|
name | path | string | yes | Name of the local group |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not 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
| Name | In | Type | Required | Description |
|---|
name | path | string | yes | Name of the local group |
|---|
Request body
application/json: GroupMembersRequest
| Name | Type | Required | Description |
|---|
groups | array of string | | Groups to add as nested groups. A group that would contain itself, directly or through other groups, is refused (error.identity.group_cycle). |
|---|
users | array of string | | Users to add (local users). |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | GroupView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not 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
| Name | In | Type | Required | Description |
|---|
name | path | string | yes | Name of the local group |
|---|
Request body
application/json: GroupMembersRequest
| Name | Type | Required | Description |
|---|
groups | array of string | | Groups to add as nested groups. A group that would contain itself, directly or through other groups, is refused (error.identity.group_cycle). |
|---|
users | array of string | | Users to add (local users). |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | GroupView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not 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
| Name | In | Type | Required | Description |
|---|
name | path | string | yes | Name of the local group |
|---|
member | path | string | yes | Name of the nested group |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not 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
| Name | In | Type | Required | Description |
|---|
name | path | string | yes | Name of the local group |
|---|
username | path | string | yes | User name of the account |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not 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
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
| Name | Type | Required | Description |
|---|
autoUnlockIntervalSeconds | integer (int64) | yes | 1 to 604800 seconds (seven days); 0 (the lockout lifted by an administrator only) is refused. |
|---|
description | string or null | | Text for administrators (kept when absent). |
|---|
failedAttemptIntervalSeconds | integer (int64) | yes | 1 to 604800 seconds (seven days). |
|---|
maxFailedAttempts | integer (int32) | yes | 1 to 1000. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | LockoutPolicyView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
POST /v1/identity/login
Password login.
- CLI
kyvernon login <username>
Request body
application/json: LoginRequest
| Name | Type | Required | Description |
|---|
kind | string or null | | interactive (default) or api. |
|---|
password | string | yes | Password. |
|---|
username | string | yes | Username. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | LoginResponse |
|---|
| 401 | Not 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
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
POST /v1/identity/mfa/complete
Completes an MFA login.
- CLI
kyvernon login <username> --code <code>
Request body
application/json: CompleteMfaRequest
| Name | Type | Required | Description |
|---|
code | string | yes | Six-digit code. |
|---|
pendingToken | string | yes | Pending token from the login response. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | SessionView |
|---|
| 401 | Not 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
| Name | In | Type | Required | Description |
|---|
state | query | string | yes | State from the start response. |
|---|
code | query | string | yes | Authorization code. |
|---|
Responses
| Status | Description | Schema |
|---|
| 303 | Session cookies set; Location: / | |
|---|
| 401 | Not 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
| Status | Description | Schema |
|---|
| 200 | OK | OidcAdminView |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
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
| Name | Type | Required | Description |
|---|
clientId | string | yes | Client id. |
|---|
clientSecret | string or null | | Client secret (write-only). Blank or absent keeps the stored one. |
|---|
groupsClaim | string | | Claim with the group names (default groups). |
|---|
issuer | string | yes | Issuer URL. |
|---|
loginTtlSeconds | integer (int64) | yes | How long a started sign-in stays valid, 60 to 3600 seconds. |
|---|
redirectUri | string | yes | Redirect URI, normally https://<controller>/v1/identity/oidc/callback. |
|---|
scopes | array of string | | Scopes beyond openid. |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | OidcAdminView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
| 412 | Failed precondition; the error body says which | ErrorBody |
|---|
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
| Status | Description | Schema |
|---|
| 204 | Removed | |
|---|
| 403 | Permission denied; args.privilege names the missing privilege | ErrorBody |
|---|
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
| Status | Description | Schema |
|---|
| 200 | Provider URL; sets the kyv_oidc browser-binding cookie | OidcStartResponse |
|---|
| 501 | Not configured on this controller | ErrorBody |
|---|
GET /v1/identity/password-policy
Reads the password policy (Kyvernon.Identity.ManagePolicy).
- CLI
kyvernon users password-policy
Responses
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
| Name | Type | Required | Description |
|---|
description | string or null | | Text for administrators (kept when absent). |
|---|
maxLength | integer | yes | Longest password, at most maxLengthCeiling (256) and not below minLength. |
|---|
minLength | integer | yes | Shortest password, at least minLengthFloor (12). |
|---|
Responses
GET /v1/identity/permissions
Permissions defined on an entity.
- CLI
kyvernon permissions list <entity>
Parameters
| Name | In | Type | Required | Description |
|---|
entityId | query | string | yes | Entity id. |
|---|
Responses
PUT /v1/identity/permissions
Sets (creates or replaces) a permission.
- CLI
kyvernon permissions set <entity> <principal> --role <role>
Request body
application/json: SetPermissionRequest
| Name | Type | Required | Description |
|---|
entityId | string | yes | Entity id. |
|---|
principal | PrincipalView | yes | Principal. |
|---|
propagate | boolean | | Propagate (default true). |
|---|
roleId | string | yes | Role id. |
|---|
Responses
DELETE /v1/identity/permissions/{id}
Removes a permission.
- CLI
kyvernon permissions remove <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the permission |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
GET /v1/identity/privileges
The privilege catalogue.
- CLI
kyvernon privileges list
Responses
GET /v1/identity/roles
Lists roles.
- CLI
kyvernon roles list
Responses
| Status | Description | Schema |
|---|
| 200 | OK | array of RoleView |
|---|
POST /v1/identity/roles
Creates a role.
- CLI
kyvernon roles create <name>
Request body
application/json: RoleRequest
| Name | Type | Required | Description |
|---|
description | string | | Description. |
|---|
name | string | yes | Name. |
|---|
privileges | array of string | yes | Privileges from the catalogue. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | RoleView |
|---|
PUT /v1/identity/roles/{id}
Updates a role.
- CLI
kyvernon roles update <id> --name <name>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the role |
|---|
Request body
application/json: RoleRequest
| Name | Type | Required | Description |
|---|
description | string | | Description. |
|---|
name | string | yes | Name. |
|---|
privileges | array of string | yes | Privileges from the catalogue. |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
DELETE /v1/identity/roles/{id}
Deletes a role.
- CLI
kyvernon roles delete <id>
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the role |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
GET /v1/identity/self
The caller's identity.
- CLI
kyvernon whoami
Responses
| Status | Description | Schema |
|---|
| 200 | OK | WhoAmI |
|---|
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
| Name | Type | Required | Description |
|---|
code | string | yes | Six-digit code. |
|---|
Responses
POST /v1/identity/self/mfa/enrol
Starts TOTP enrolment for the caller.
- CLI
kyvernon self mfa enrol
Responses
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
| Name | Type | Required | Description |
|---|
currentPassword | string or null | | Current password (required for self-service). |
|---|
newPassword | string | yes | New password. |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
GET /v1/identity/sessions
Active sessions (administrator).
- CLI
kyvernon sessions list
Responses
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
| Name | In | Type | Required | Description |
|---|
id | path | string | yes | Id of the session |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
GET /v1/identity/users
Lists users.
- CLI
kyvernon users list
Responses
| Status | Description | Schema |
|---|
| 200 | OK | array of UserView |
|---|
POST /v1/identity/users
Creates a local user.
- CLI
kyvernon users create <username>
Request body
application/json: CreateUserRequest
| Name | Type | Required | Description |
|---|
displayName | string | | Display name. |
|---|
email | string | | E-mail. |
|---|
groups | array of string | | Groups. |
|---|
password | string | yes | Initial password. |
|---|
rotationRequired | boolean | | Require a password change at first login (default true). |
|---|
username | string | yes | Username. |
|---|
Responses
| Status | Description | Schema |
|---|
| 201 | Created | UserView |
|---|
GET /v1/identity/users/{username}
One user, with the lockout state (locked, lockedUntil).
- CLI
kyvernon users get <username>
Parameters
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Responses
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
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Request body
application/json: UpdateUserRequest
| Name | Type | Required | Description |
|---|
displayName | string or null | | Display name. |
|---|
email | string or null | | E-mail address. |
|---|
groups | array of string or null | | The local groups the user is a direct member of (replaces the set; groups that come from an identity provider stay). |
|---|
Responses
| Status | Description | Schema |
|---|
| 200 | OK | UserView |
|---|
| 400 | Invalid argument; the error body names the field | ErrorBody |
|---|
| 404 | Not found (or not visible to the caller) | ErrorBody |
|---|
DELETE /v1/identity/users/{username}
Deletes a user.
- CLI
kyvernon users delete <username>
Parameters
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; 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
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Responses
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
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Request body
application/json: CreateApiTokenRequest
| Name | Type | Required | Description |
|---|
name | string | yes | Label (1..=64 characters). |
|---|
ttlSeconds | integer (int64) or null | | Lifetime 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
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
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
id | path | string | yes | Id of the API token |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
PUT /v1/identity/users/{username}/enabled
Enables or disables a user.
- CLI
kyvernon users enable <username>
Parameters
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Request body
application/json: SetEnabledRequest
| Name | Type | Required | Description |
|---|
enabled | boolean | yes | Enabled. |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
DELETE /v1/identity/users/{username}/mfa
Resets a user's MFA enrolment.
- CLI
kyvernon users reset-mfa <username>
Parameters
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
POST /v1/identity/users/{username}/password
Sets another user's password (administrator).
- CLI
kyvernon users set-password <username>
Parameters
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Request body
application/json: ChangePasswordRequest
| Name | Type | Required | Description |
|---|
currentPassword | string or null | | Current password (required for self-service). |
|---|
newPassword | string | yes | New password. |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
PUT /v1/identity/users/{username}/service-account
Flags or unflags a service account (administrator).
- CLI
kyvernon users service-account <username>
Parameters
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Request body
application/json: ServiceAccountRequest
| Name | Type | Required | Description |
|---|
serviceAccount | boolean | yes | Whether the account is a service account. |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
DELETE /v1/identity/users/{username}/sessions
Revokes all sessions of a user.
- CLI
kyvernon users revoke-sessions <username>
Parameters
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
POST /v1/identity/users/{username}/unlock
Lifts a lockout (administrator).
- CLI
kyvernon users unlock <username>
Parameters
| Name | In | Type | Required | Description |
|---|
username | path | string | yes | User name of the account |
|---|
Responses
| Status | Description | Schema |
|---|
| 204 | Done; no body | |
|---|
Version 0.1.