Skip to main content

POST /api/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​

FieldTypeRequiredDescription
ttagstringyesCanonical base64 hidden link naming the key. Required, and a zero-length one is refused: it names no key and is not a wildcard.
systemIdintegeryesThe 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.
principalIdinteger or stringyesA non-negative integer, or a DECIMAL STRING for an id above 2^53. This is the same spelling POST /api/keys/export takes and the same spelling this surface projects.
rightsvariant or variantyesThe 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.
maxUsageintegernoOmit 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.
startTimestringnobase64 of EXACTLY 8 bytes -- a raw stamp, not a date string and not a number; there is no conversion on this field. Omit to send the eight zero bytes that mean "unset".
endTimestringnobase64 of exactly 8 bytes. Omit for "unset".

Example

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

Responses​

200​

The entry landed, verified by a fresh read.

FieldTypeRequiredDescription
codestringnoAbsent on success; NOT_VERIFIED when the read-back disagrees.
operationstringnoWhich key-server operation was sent.
verifiedbooleanno
requestedRightsinteger or nullnoNull on revoke, which takes no rights.
requestedRightNamesarray or nullno
entryAclEntry or variantnoThe matching entry from the fresh read, or null. Null is the SUCCESS case on revoke.
aclAclInfono
detailstringno

entry — AclEntry

FieldTypeRequiredDescription
principalIdstringnoDecimal string. Feeds straight back into the grant/update/revoke routes and into export.
systemIdintegerno
aclEntryIdstringnobase64 opaque handle
aclIdstringnobase64 opaque handle
rightsintegernoThe 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.
rightNamesarray of string (OWNER, READ, WRITE, MANDATORY_GROUP, HOST_MATRIX)no
maxUsageintegerno-1 means no limit.
userRightintegerno
startTimestringnobase64 of the raw 8-byte stamp
startTimeUnsetbooleannoTrue when the stamp is all zero -- the "no window" default, reported rather than converted into a date it does not mean.
endTimestringnobase64 of the raw 8-byte stamp
endTimeUnsetbooleanno

AclInfo

FieldTypeRequiredDescription
aclIdstringno
hiddenLinkobjectnoThe 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.
expiredbooleanno
entryCountintegerno
entriesarray of AclEntrynoOne 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": 0,
    "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": 0,
        "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.

401​

No live session, or a DPoP proof that did not verify.

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.

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.

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.

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.

StatusMeaning
400The 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.
401No live session, or a DPoP proof that did not verify. 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.
403OBJECT_NOT_IN_CREDENTIAL_SCOPE or ACCESS_DENIED.
404ACL_NOT_FOUND -- no ACL resolved for that link, and NO grant was attempted.
409NOT_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.
500A 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.
502READBACK_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.
503A 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.