`POST /api/v1/keys/acl/grant`

Add an ACL entry giving a principal rights over a key.

Adds an ACL entry, then re-reads the ACL and verifies. The underlying call resolves with nothing and clears its own dirty-field set, so a resolved call proves only that the key server did not refuse.

Verification is a MASK TEST -- (observed & requested) === requested -- never equality, because the key server widens rights. Compare requestedRights with entry.rights to see the widening.

Omitting maxUsage means no limit. Omitting startTime/endTime sends the eight zero bytes that mean "unset", which is what the live grant path sends; when present each must decode to EXACTLY 8 bytes -- it is a raw stamp, not a date string and not a number.

A group id works here exactly as a user id does, and granting a key to a group is the usual reason to have made one.

Authentication

Send the session id as Authorization: Bearer <session id>, and an RFC 9449 DPoP proof in the DPoP header if your session is bound to a key. The two are required together, not as alternatives — see Authenticating and Proving you hold your key.

This surface sets no cookie

There is no session cookie on any response and none is read on any request. Do not set credentials: "include" on a browser fetch.

Request

Field	Type	Required	Description
`ttag`	`string`	yes	Canonical base64 hidden link naming the key. Required, and a zero-length one is refused: it names no key and is not a wildcard.
`systemId`	`integer`	yes	The one field on an ACL entry that is a NUMBER rather than an 8-byte value. Read it from the server; a wrong one addresses a principal that does not exist.
`principalId`	`integer` or `string`	yes	A non-negative integer, or a DECIMAL STRING for an id above 2^53. This is the same spelling `POST /api/v1/keys/export` takes and the same spelling this surface projects.
`rights`	`variant` or `variant`	yes	The rights to grant, as a bitmask or as names. The key server WIDENS what you send, so the response reports the requested mask and the observed one separately.
`maxUsage`	`integer`	no	Omit for no limit. Anything below -1 is refused here because the underlying setter throws synchronously, which would reach you as a `500` rather than as a bad request. The count is consumed on every use of the key under this entry, warm or cold, on the key server and through a remote engine; -1 (USAGE_NO_LIMIT) is unlimited; a group entry's count is consumed by any member's use.
`startTime`	`string`	no	base64 of EXACTLY 8 bytes: big-endian 64-bit UTC seconds (`struct.pack(">Q", s)`) -- not a date string and not a JSON number; there is no conversion on this field. Omit to send the eight zero bytes that mean "unset". A start/end bound is enforced on every use, warm or cold.
`endTime`	`string`	no	base64 of exactly 8 bytes: big-endian 64-bit UTC seconds, as `startTime`. Omit for "unset". A start/end bound is enforced on every use: a use after the end is refused even on a session the entry already served.

Example

{
  "ttag": "...",
  "systemId": 0,
  "principalId": 0,
  "rights": 0,
  "maxUsage": -1,
  "startTime": "...",
  "endTime": "..."
}

Responses

`200`

The entry landed, verified by a fresh read.

Field	Type	Required	Description
`code`	`string`	no	Absent on success; `NOT_VERIFIED` when the read-back disagrees.
`operation`	`string`	no	Which key-server operation was sent.
`verified`	`boolean`	no
`requestedRights`	`integer` or `null`	no	Null on revoke, which takes no rights.
`requestedRightNames`	`array` or `null`	no
`entry`	`AclEntry` or `variant`	no	The matching entry from the fresh read, or null. Null is the SUCCESS case on revoke.
`acl`	`AclInfo`	no
`detail`	`string`	no

entry — AclEntry

Field	Type	Required	Description
`principalId`	`string`	no	Decimal string. Feeds straight back into the grant/update/revoke routes and into export.
`systemId`	`integer`	no
`aclEntryId`	`string`	no	base64 opaque handle
`aclId`	`string`	no	base64 opaque handle
`rights`	`integer`	no	The rights bitmask AS THE KEY SERVER HOLDS IT. The key server WIDENS what is asked for -- requesting WRITE reads back as WRITE\|READ -- so test this with a mask AND, never with equality.
`rightNames`	array of `string` (`OWNER`, `READ`, `WRITE`, `MANDATORY_GROUP`, `HOST_MATRIX`)	no
`maxUsage`	`integer`	no	The number of uses REMAINING; -1 means no limit. The count is consumed on every use of the key under this entry, warm or cold, on the key server and through a remote engine; a start/end bound is enforced on every use; -1 (USAGE_NO_LIMIT) is unlimited; a group entry's count is consumed by any member's use.
`userRight`	`integer`	no
`startTime`	`string`	no	the key server's time_t as big-endian 64-bit UTC seconds -- 8 raw bytes, base64 (`struct.pack(">Q", s)`)
`startTimeUnset`	`boolean`	no	True when the stamp is all zero -- the "no window" default, reported rather than converted into a date it does not mean.
`endTime`	`string`	no	the key server's time_t as big-endian 64-bit UTC seconds -- 8 raw bytes, base64 (`struct.pack(">Q", s)`)
`endTimeUnset`	`boolean`	no

AclInfo

Field	Type	Required	Description
`aclId`	`string`	no
`hiddenLink`	`object`	no	The hidden link as the key server reports it on the ACL object. Its shape is the key server's and is passed through unchanged; do not depend on it. Use the `ttag` you sent.
`expired`	`boolean`	no
`entryCount`	`integer`	no
`entries`	array of `AclEntry`	no	One ACL entry -- one principal's rights over one key.

Example

{
  "code": "...",
  "operation": "...",
  "verified": true,
  "requestedRights": 0,
  "requestedRightNames": [
    "..."
  ],
  "entry": {
    "principalId": "...",
    "systemId": 0,
    "aclEntryId": "...",
    "aclId": "...",
    "rights": 0,
    "rightNames": [
      "OWNER"
    ],
    "maxUsage": -1,
    "userRight": 0,
    "startTime": "...",
    "startTimeUnset": true,
    "endTime": "...",
    "endTimeUnset": true
  },
  "acl": {
    "aclId": "...",
    "hiddenLink": {},
    "expired": true,
    "entryCount": 0,
    "entries": [
      {
        "principalId": "...",
        "systemId": 0,
        "aclEntryId": "...",
        "aclId": "...",
        "rights": 0,
        "rightNames": [
          "..."
        ],
        "maxUsage": -1,
        "userRight": 0,
        "startTime": "...",
        "startTimeUnset": true,
        "endTime": "...",
        "endTimeUnset": true
      }
    ]
  },
  "detail": "..."
}

`400`

The request was refused before anything was sent to the key server.

Most 400s on this surface carry code: BAD_REQUEST and a detail naming the field and saying what the key server would otherwise have done with it. A large share of them exist because the value would have been ACCEPTED downstream and quietly meant something else -- an empty string that reaches the wire as "mint a new key", a zero-length identifier that names no object, a numeric flag word that clears bits the caller did not name.

INVALID_ARGUMENT is the one 400 that DID reach the key server: the key server itself refused the argument (ERR_INVALID_ARGUMENT), and detail is its own sentence. On POST /api/v1/certificates/enroll that is a certificate that cannot authenticate -- certificate not permitted for authentication: keyUsage is present without digitalSignature (...), ... extendedKeyUsage is present without clientAuth (...), or certificate expired at enrolment: notAfter <UTC> ... -- and a multi-certificate body that carries one such leaf persists nothing.

KEY_UNWRAP_FAILED reached the key server too, on POST /api/v1/keys/import with format WRAPPED: the wrapped key did not unwrap under the key server's trust certificate -- wrapped to another key, by another method, or damaged. Nothing was stored for that key.

`401`

No live session, a DPoP proof that did not verify, or a certificate session whose certificate the key server now refuses.

SESSION_NOT_FOUND -- the credential names no session this Gateway holds. SESSION_EXPIRED -- it aged out. Both carry reauth: true; obtain a new credential rather than retrying.

PROOF_* -- the sender constraint refused. See the DPoP section of this document for the full table; PROOF_MALFORMED is a 400 and PROOF_REPLAY_CACHE_FULL a 503, and the rest are here.

SCOPED_CREDENTIAL_EXPIRED -- a scoped browser credential passed its fixed lifetime. Use does not extend it: an idle timeout would be refreshed by exactly the traffic a stolen handle produces.

CERTIFICATE_REVOKED -- on a session established by certificate login, the key server re-checks the certificate that session was established with on its operations, and it is now named by revocation evidence. detail is the key server's sentence. The Gateway answers this once and then ENDS everything that service holds or minted here -- its sessions, the delegated sessions and the scoped credentials it minted -- so a later operation on any of them is SESSION_NOT_FOUND. Log in with a different certificate.

SSO_SESSION_EXPIRED -- a single-sign-on session (POST /api/v1/session/oidc) reached its lifetime, or was idle past its binding's idle bound; it has been ended. Sign in again.

SENDER_KEY_RETIRED -- the session's registered sender key was rotated out and its overlap has passed (see "The registered service's credential lifecycle"); the session is closed with this answer. SERVICE_REGISTRATION_ENDED -- the registration a service credential was issued under was removed or narrowed on this Gateway; it has ended. Both are final for that credential.

`403`

OBJECT_NOT_IN_CREDENTIAL_SCOPE or ACCESS_DENIED.

`404`

ACL_NOT_FOUND -- no ACL resolved for that link, and NO grant was attempted.

`409`

NOT_VERIFIED -- the key server did not refuse, and the read-back does not show the requested rights. Reported as a failure because the read-back IS the verification.

`410`

KEY_EXPIRED (retryable: false) -- the key the request named was expired (POST /api/v1/keys/expire). Its record is kept, and every use of it -- decrypt, encrypt under its t-Tag, export, an access-control grant or update -- is refused, on every key server of the deployment. An expiry is never undone; the key's owner may still remove it.

`500`

A fault rather than a refusal.

OP_FAILED is the catch-all: the key server refused in words that match no classified pattern, so the Gateway cannot say more than that the operation did not happen. Some key server refusals that are conceptually a caller error arrive here rather than as a 4xx, because the wire carries no distinguishing code -- where a route can recognise one from its message it maps it, and each such mapping is documented on the operation.

`502`

READBACK_FAILED -- the write was sent and not refused, and the verifying read resolved no ACL, so what landed cannot be reported. An unverifiable write is not reported as a success.

`503`

A capacity ceiling or a missing deployment prerequisite. retryable says which.

A scope of session or process names the ceiling that was hit, and the response carries Retry-After.

BUILD_NOT_ADMITTED (scope: process, retryable: true, Retry-After): the key server does not admit this Gateway's client build. Every key-server connection the Gateway opens attests the signed release it runs (TE_RELEASE_MANIFEST) right after it authenticates; while that attestation is refused -- the release is not registered at the key server's code-signing level, the level was raised under it, or the installed files no longer match the signed manifest -- every route but GET /api/v1/health and GET /api/v1/ready answers this, and detail names the cause. It is never a 401 or a 403: no credential or role of the caller's is at fault. The Gateway re-attempts on a timer and recovers without a restart once the key server admits it; GET /api/v1/ready says when.

CAPACITY_UNAVAILABLE (scope: process, retryable: true, Retry-After): this Gateway is serving its maximum number of requests at once, or cannot track another allowance, or (on a certificate login) is recording its maximum of live certificate sessions -- in which case the session the login created has been closed. Nothing else was sent to the key server. See "Rate and capacity limits" above.

`413`

PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.

`429`

RATE_LIMITED (retryable: true, Retry-After) -- the allowance this request is charged to is spent: the login allowance of its network source (before authentication), or the allowance, the concurrency ceiling or the live-session ceiling of the identity it was verified as -- shared by every session that identity holds, including every delegated and scoped credential a service minted. It carries no scope. Nothing was sent to the key server; on a login refused after authentication, the session it created has been closed. See "Rate and capacity limits" above.

Error handling

Every failure answers JSON carrying at least code and detail. Match on code — detail is written for a human debugging the call and its wording is not part of the contract. See the error model.

Status	Meaning
`400`	The request was refused before anything was sent to the key server. Most `400`s on this surface carry `code: BAD_REQUEST` and a `detail` naming the field and saying what the key server would otherwise have done with it. A large share of them exist because the value would have been ACCEPTED downstream and quietly meant something else -- an empty string that reaches the wire as "mint a new key", a zero-length identifier that names no object, a numeric flag word that clears bits the caller did not name. `INVALID_ARGUMENT` is the one `400` that DID reach the key server: the key server itself refused the argument (`ERR_INVALID_ARGUMENT`), and `detail` is its own sentence. On `POST /api/v1/certificates/enroll` that is a certificate that cannot authenticate -- `certificate not permitted for authentication: keyUsage is present without digitalSignature (...)`, `... extendedKeyUsage is present without clientAuth (...)`, or `certificate expired at enrolment: notAfter <UTC> ...` -- and a multi-certificate body that carries one such leaf persists nothing. `KEY_UNWRAP_FAILED` reached the key server too, on `POST /api/v1/keys/import` with format `WRAPPED`: the wrapped key did not unwrap under the key server's trust certificate -- wrapped to another key, by another method, or damaged. Nothing was stored for that key.
`401`	No live session, a DPoP proof that did not verify, or a certificate session whose certificate the key server now refuses. `SESSION_NOT_FOUND` -- the credential names no session this Gateway holds. `SESSION_EXPIRED` -- it aged out. Both carry `reauth: true`; obtain a new credential rather than retrying. `PROOF_*` -- the sender constraint refused. See the DPoP section of this document for the full table; `PROOF_MALFORMED` is a `400` and `PROOF_REPLAY_CACHE_FULL` a `503`, and the rest are here. `SCOPED_CREDENTIAL_EXPIRED` -- a scoped browser credential passed its fixed lifetime. Use does not extend it: an idle timeout would be refreshed by exactly the traffic a stolen handle produces. `CERTIFICATE_REVOKED` -- on a session established by certificate login, the key server re-checks the certificate that session was established with on its operations, and it is now named by revocation evidence. `detail` is the key server's sentence. The Gateway answers this once and then ENDS everything that service holds or minted here -- its sessions, the delegated sessions and the scoped credentials it minted -- so a later operation on any of them is `SESSION_NOT_FOUND`. Log in with a different certificate. `SSO_SESSION_EXPIRED` -- a single-sign-on session (`POST /api/v1/session/oidc`) reached its lifetime, or was idle past its binding's idle bound; it has been ended. Sign in again. `SENDER_KEY_RETIRED` -- the session's registered sender key was rotated out and its overlap has passed (see "The registered service's credential lifecycle"); the session is closed with this answer. `SERVICE_REGISTRATION_ENDED` -- the registration a service credential was issued under was removed or narrowed on this Gateway; it has ended. Both are final for that credential.
`403`	`OBJECT_NOT_IN_CREDENTIAL_SCOPE` or `ACCESS_DENIED`.
`404`	`ACL_NOT_FOUND` -- no ACL resolved for that link, and NO grant was attempted.
`409`	`NOT_VERIFIED` -- the key server did not refuse, and the read-back does not show the requested rights. Reported as a failure because the read-back IS the verification.
`410`	`KEY_EXPIRED` (`retryable: false`) -- the key the request named was expired (`POST /api/v1/keys/expire`). Its record is kept, and every use of it -- decrypt, encrypt under its t-Tag, export, an access-control grant or update -- is refused, on every key server of the deployment. An expiry is never undone; the key's owner may still remove it.
`500`	A fault rather than a refusal. `OP_FAILED` is the catch-all: the key server refused in words that match no classified pattern, so the Gateway cannot say more than that the operation did not happen. Some key server refusals that are conceptually a caller error arrive here rather than as a `4xx`, because the wire carries no distinguishing code -- where a route can recognise one from its message it maps it, and each such mapping is documented on the operation.
`502`	`READBACK_FAILED` -- the write was sent and not refused, and the verifying read resolved no ACL, so what landed cannot be reported. An unverifiable write is not reported as a success.
`503`	A capacity ceiling or a missing deployment prerequisite. `retryable` says which. A `scope` of `session` or `process` names the ceiling that was hit, and the response carries `Retry-After`. `BUILD_NOT_ADMITTED` (`scope: process`, `retryable: true`, `Retry-After`): the key server does not admit this Gateway's client build. Every key-server connection the Gateway opens attests the signed release it runs (`TE_RELEASE_MANIFEST`) right after it authenticates; while that attestation is refused -- the release is not registered at the key server's code-signing level, the level was raised under it, or the installed files no longer match the signed manifest -- every route but `GET /api/v1/health` and `GET /api/v1/ready` answers this, and `detail` names the cause. It is never a `401` or a `403`: no credential or role of the caller's is at fault. The Gateway re-attempts on a timer and recovers without a restart once the key server admits it; `GET /api/v1/ready` says when. `CAPACITY_UNAVAILABLE` (`scope: process`, `retryable: true`, `Retry-After`): this Gateway is serving its maximum number of requests at once, or cannot track another allowance, or (on a certificate login) is recording its maximum of live certificate sessions -- in which case the session the login created has been closed. Nothing else was sent to the key server. See "Rate and capacity limits" above.
`413`	`PAYLOAD_TOO_LARGE` (`retryable: false`) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.
`429`	`RATE_LIMITED` (`retryable: true`, `Retry-After`) -- the allowance this request is charged to is spent: the login allowance of its network source (before authentication), or the allowance, the concurrency ceiling or the live-session ceiling of the identity it was verified as -- shared by every session that identity holds, including every delegated and scoped credential a service minted. It carries no `scope`. Nothing was sent to the key server; on a login refused after authentication, the session it created has been closed. See "Rate and capacity limits" above.

Authentication​

Request​

Responses​

200​

400​

401​

403​

404​

409​

410​

500​

502​

503​

413​

429​

Error handling​