POST /api/session/certificate

Certificate login, leg 2: answer the challenge and receive a bearer credential.

Completes an X.509 certificate login. Send the pending id from leg 1 and the signature over the challenge; receive a session id as a bearer credential.

A service has no cookie jar, which is why this credential travels in the body.

If this Gateway holds a service registration matching the certificate's principal, the session is associated with it -- and is then sender-constrained to that registration's senderKey, so every subsequent call must carry a DPoP proof. A certificate login with no matching registration is a perfectly good session that is simply not constrained, and by rule it cannot delegate.

WARNING: the registered senderKey must not be the same key as the login certificate's, and a login that would produce that arrangement is refused with the session closed. AM08 makes the login key a signing oracle over bytes chosen upstream of the caller. Today an RS256 proof and an AM08 response are not interchangeable, but only because of an encoding-length accident rather than a designed separation -- so a change to either construction would remove the separation with nothing failing. Generate a separate keypair for request signing.

Authentication

No session required. This operation is reachable without an Authorization header. See Authenticating.

Request

Field	Type	Required	Description
pending	string	yes	The id from leg 1. Single use.
signature	string	yes	Raw PKCS#1 v1.5 signature over the 32 challenge bytes, base64. No digest, no DigestInfo.

Example

{
  "pending": "...",
  "signature": "..."
}

Responses

200

Authenticated by certificate.

Field	Type	Required	Description
session	string	yes	The bearer credential.
loginId	string	yes	The principal id the key server resolved
serviceKey	string or null	no	The registry key this login resolves to, or null if none.
subjectHint	string	no
service	string or null	no	The matched service registration's id, or null. Null means this session is not sender-constrained and cannot delegate.
ks	KsAddress	yes
system	SystemBlock	no	The cached boot snapshot of the key server this Gateway fronts. It carries no credential: the boot call that produces it cannot return one.
detail	string	yes

KsAddress

Field	Type	Required	Description
host	string	no
port	integer	no

Example

{
  "session": "...",
  "loginId": "...",
  "serviceKey": "...",
  "subjectHint": "...",
  "service": "...",
  "ks": {
    "host": "...",
    "port": 0
  },
  "system": {},
  "detail": "..."
}

400

MISSING_PENDING, MISSING_SIGNATURE, MALFORMED_SIGNATURE, or SENDER_KEY_IS_LOGIN_KEY. The last one is a refusal of a configuration, not of the request: no session was left open.

401

SIGNATURE_REJECTED -- the certificate IS enrolled and the signature did not verify, so what failed is proof of the private key. See the construction warning on leg 1. Or CERTIFICATE_NOT_ENROLLED -- enrolment is by exact digest, not by chain: a certificate signed by a trusted CA is still refused until the leaf itself is enrolled.

403

PRINCIPAL_DISABLED.

404

PENDING_NOT_FOUND -- that id was never issued, was already used (single use, consumed by the first answer whether it succeeded or failed), or expired. Nothing was sent to the key server. Start again at leg 1.

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.

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	MISSING_PENDING, MISSING_SIGNATURE, MALFORMED_SIGNATURE, or SENDER_KEY_IS_LOGIN_KEY. The last one is a refusal of a configuration, not of the request: no session was left open.
401	SIGNATURE_REJECTED -- the certificate IS enrolled and the signature did not verify, so what failed is proof of the private key. See the construction warning on leg 1. Or CERTIFICATE_NOT_ENROLLED -- enrolment is by exact digest, not by chain: a certificate signed by a trusted CA is still refused until the leaf itself is enrolled.
403	PRINCIPAL_DISABLED.
404	PENDING_NOT_FOUND -- that id was never issued, was already used (single use, consumed by the first answer whether it succeeded or failed), or expired. Nothing was sent to the key server. Start again at leg 1.
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.