POST /keys/grant

Grant a user access to a key

Adds grantee to the key's ACL. The caller must be the owner. Returns the resolved grantee identity.

Authentication

Requires the X-Session header (the opaque session id from POST /login). See Authentication.

Request

Field	Type	Required	Description
ttag	string (base64)	yes	Base64 key handle of the key to grant access to.
grantee	string	yes	Username to grant access to.

Example

{
  "ttag": "dGFnLWJhc2U2NC1leGFtcGxl",
  "grantee": "bob"
}

Responses

200

Access granted.

Field	Type	Required	Description
ok	boolean	yes
grantee	object	yes

grantee object

Field	Type	Required	Description
user	string	yes
systemId	integer	yes
principalId	string	yes	Hex-encoded principal id (16 hex chars).

Example

{
  "ok": true,
  "grantee": {
    "user": "bob",
    "systemId": 1002,
    "principalId": 1122334455667788
  }
}

400

Validation error: missing fields, invalid JSON, or body > 1 MB.

401

Authentication required. Two shapes share this status: a session-layer 401 (a plain Error, no reauth flag) means a missing or unknown/expired X-Session — re-login for a new session id; a token-layer 401 (ReauthError with reauth: true) means the server-held token expired — re-run POST /login and retry.

403

kS RBAC/ACL denial — a real authorization refusal. Surface it; retrying will not help until access is granted.

500

Other kS operation error.

Error handling

This endpoint can return the statuses below. For request bodies and the client action per status, see the full error contract.

Status	Meaning
400	Validation error: missing fields, invalid JSON, or body > 1 MB.
401	Authentication required. Two shapes share this status: a session-layer 401 (a plain Error, no reauth flag) means a missing or unknown/expired X-Session — re-login for a new session id; a token-layer 401 (ReauthError with reauth: true) means the server-held token expired — re-run POST /login and retry.
403	kS RBAC/ACL denial — a real authorization refusal. Surface it; retrying will not help until access is granted.
500	Other kS operation error.

Distinguish 401-reauth from 403

A 401 with { "reauth": true } means the server-held token expired — re-run POST /login and retry. A 403 is a real authorization denial — surface it; retrying will not help.