Skip to content

Users and Authentication

A user is an account that signs in to Gridone, whether a person using the web app or an application calling the API. Every user holds exactly one role, which decides what the account may do.


Users

Field Description
username Unique sign-in name, 3 to 64 characters
password 5 to 72 characters, stored hashed. Required for a person. Deprecated for service accounts: use service keys. Password sign-in for service accounts will be removed.
role Id of a built-in or custom role. Defaults to operator.
type user for a person, service_account for an application. Only a service account can hold service keys.
name, email, title Profile fields, all optional
is_blocked Whether the account is currently refused. See Blocking.

Users are managed from the Users page of the web app or through the API. Creating, updating, deleting, blocking and unblocking a user requires the users:write permission, which only the built-in admin role holds: a custom role cannot be given it. A user can only be given a role whose permissions the caller already holds. An administrator cannot delete or block their own account.

Blocking a user

Blocking is the way to lock an account out immediately: every request from a blocked user is refused, including token refresh, until the account is unblocked. Prefer blocking over deletion when an account may need to come back, or when its history should remain attributable.


Service accounts and keys

A service account is the account another system uses to call the API: a supervision platform reading faults, an integration sending commands. It holds a role like any user, and signs in with service keys instead of a password.

Create one from the Service accounts tab of the Users page, or through the API by choosing the service-account type and leaving out the password. Give it the narrowest role that does the job: viewer for a system that only reads.

Password sign-in for service accounts is deprecated and will be removed. It remains available for existing integrations while they move to service keys; new integrations should use keys only.

From the account's page, you can issue a key with a label and an optional expiry, list that account's keys, or revoke a key. Listing requires users:read; issuing and revoking require users:write. See the API reference for the request details.

  • A key looks like gd_sk_ followed by 43 characters. It is shown once, in the answer that issues it: Gridone keeps only its SHA-256, so a lost key cannot be recovered, only revoked and replaced.
  • A key acts with the role its account holds at the time of each request. Issuing a key follows the same rule as assigning a role: the caller must hold every permission of the account's role.
  • Present the key as a bearer credential. A key is never accepted from a cookie.
  • The account's page shows when each key was last used, to the minute.
  • An expired or revoked key is refused. A key of a blocked account is refused until the account is unblocked. Deleting the account deletes its keys.

The admin account and first startup

Gridone ships with no account. On the first start against an empty database it creates one user, admin, with the admin role and the password given by the GRIDONE_ADMIN_PASSWORD environment variable.

  • If no user exists and the variable is unset, the server refuses to start and says why. It never seeds a credential nobody knows.
  • The variable is read only while the database has no user. Once any account exists it has no effect; changing it later does not reset the password.
  • The password follows the same rules as any user password.

After the first sign-in, change the password from your profile, and consider unsetting the variable.

Keep two administrators

Gridone has no email-based password recovery. If the only administrator loses their password, recovery means editing the database by hand. Create a second admin account and store both passwords in a team vault.


Authentication

Gridone authenticates with bearer tokens. Signing in with a username and password returns an access token and a refresh token; the access token identifies the caller on every subsequent request, whether it is sent as a header by an API client or as a cookie by the web app. The developer getting-started shows the sign-in exchange.

Token Default lifetime Setting
Access token 30 minutes ACCESS_TOKEN_EXPIRE_MINUTES
Refresh token 7 days REFRESH_TOKEN_EXPIRE_MINUTES

When the access token expires, the refresh token is exchanged for a new pair without asking for the password again. Signing out discards the tokens on the client side; a token that was copied elsewhere stays valid until it expires.

Tokens are signed with the server's SECRET_KEY. Set it to a fixed value in production: a server that generates a random key at startup signs every user out on each restart. Rotating the key on purpose is also the way to end every session at once.

Any signed-in user can read their own profile, including the permissions their role grants, and change their own password. Changing your own password requires the current one and needs no permission.


When a change takes effect

Change Takes effect
Block a user Immediately, on their next request
Edit the permissions of a custom role Immediately, on the next request of every user holding it
Change a user's role At their next token refresh, at most one access-token lifetime later. Until then the previous role is enforced, and the profile endpoint reports that role and its permissions.
Change or reset a password Sign-in only. Existing sessions stay valid; block the user to end them now.
Delete a user Token refresh is refused. An existing access token stays valid until it expires.
Rotate SECRET_KEY Every session ends at the next request
Revoke a service key, or reach its expiry Immediately, on the next request presenting it
Change a service account's role Immediately for its keys, on their next request