Verified Commit bc07d0d0 authored by Florian Forster's avatar Florian Forster
Browse files

docs(users): document the `Locked` and `State` fields 

Add documentation to clarify the distinction between the `Locked` and `State`
fields on the `BasicUser` type:

- `Locked`: temporary lock due to failed login attempts (Devise lockable)
- `State`: permanent administrative status (active, blocked, banned, etc.)

These fields are independent: an active user can be locked, and a blocked user
can be unlocked. This distinction is often misunderstood due to lack of
documentation in the GitLab API docs.
parent a1075a5c

users.go

+18 −5
Original line number Diff line number Diff line
@@ -337,8 +337,21 @@ type BasicUser struct { 
	ID       int64  `json:"id"`

	Username string `json:"username"`

	Name     string `json:"name"`



	// State represents the administrative status of the user account.

	// Common values: "active", "blocked", "deactivated", "banned",

	// "ldap_blocked", "blocked_pending_approval".

	//

	// This is independent from the Locked field: State tracks permanent

	// administrative actions, while Locked handles temporary login failures.

	State string `json:"state"`



	// Locked indicates whether the user account is temporarily locked due to

	// excessive failed login attempts. This is separate from administrative

	// blocking (the State field). Locks automatically expire after a configured

	// time period (default: 10 minutes).

	Locked bool `json:"locked"`



	CreatedAt *time.Time `json:"created_at"`

	AvatarURL string     `json:"avatar_url"`

	WebURL    string     `json:"web_url"`