Authentication & API keys

Authenticate API requests with a personal API key — a long-lived secret tied to one Gurita user. Every request made with the key runs as that user, with exactly their permissions.

Note: Personal API keys are an enterprise module. An administrator switches on User API Keys under Active Modules. While it is off, creating a key fails with USER_API_KEYS_DISABLED.

The UserKey header

Send the key in the Authorization header with the UserKey scheme:

Authorization: UserKey <userId>.<secret>

• <userId> is the ID of the Gurita user who owns the key.
• <secret> is the key itself. It starts with guk_.

You don't have to assemble this yourself — Gurita shows the complete header value when you create a key.

curl -H "Authorization: UserKey 64f1c2e9a7b3d40012ab34cd.guk_…" \
  "https://YOUR-DOMAIN/api/customers?page=1&size=20"

Create a key

1. Open your user profile in Gurita.
2. In the API keys card, click Create key.
3. Enter a Name that says what the key is for, e.g. Nightly CRM export.
4. Set Expires.
5. Confirm. Gurita shows the API key created dialog with the full Authorization value.
6. Copy it now. The secret is shown only once. Gurita stores only a hash, so a lost key cannot be recovered — create a new one instead.

Administrators who can edit users can also create and manage keys for other users.

Key rules

Rule	Detail
Active keys per user	At most 5. Revoke or delete one to create another.
Expiry (your own keys)	Required, and at most 1 year ahead.
Expiry (keys an admin creates for a user)	Optional. Leave it empty for a key that never expires.
Revoke	The key stops working immediately. It stays in the list, marked revoked.
Delete	Removes the key from the list.

The key list shows each key's name, the first characters of its secret, its expiry and when it was last used — handy for spotting keys nobody uses any more.

What a key can and can't do

A key acts as its user. It sees the same data, the same properties and has the same permissions as that user does in the app. If the user loses a permission, so does the key.

Some routes never accept a key, whatever the user's permissions:

• Sign-in and sessions — everything under /api/auth.
• Passwords — changing your own or another user's password.
• Key management — creating, listing, revoking or deleting API keys.

Your Gurita system may block further routes for keys. A request to one of these routes returns 403 Forbidden.

Errors

Response	Meaning
401 · USER_KEY_INVALID	The header is malformed, the key is unknown, revoked or expired.
403	The user lacks permission, or the route doesn't accept API keys.
409 · USER_KEY_LIMIT	You already have 5 active keys.
400 · USER_KEY_EXPIRES_REQUIRED / …_TOO_LONG / …_PAST / …_INVALID	The expiry date is missing, more than a year ahead, in the past, or not a date.

See Requests, paging & errors for the full error format.

Best practices

• Use a dedicated user. Create a Gurita user just for the integration and give it only the permissions it needs (see Users & Access). A leaked key can then do little harm.
• Keep keys on the server. Never put a key in a web page, a mobile app or anything else a guest can download.
• Store keys as secrets. Use environment variables or a secrets manager. Never commit them to a repository.
• Rotate. Create the new key, switch your integration over, then revoke the old one. Revoke immediately if a key may have leaked.

Related

• Requests, paging & errors
• MCP server — for AI assistants, use MCP access tokens instead of API keys.