POST /api/session/certificate

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

Completes an X.509 certificate login. Send the pending id from leg 1 and the signature over the toBeSigned value it returned; 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 signs bytes this door relays, so the login key signs a payload chosen upstream of the caller. Under ADR-0107 an RSA key signs a labelled message RSASSA-PSS, which separates it from an RS256 proof by design -- but an EC login key signs ECDSA-SHA256, and ES256 is ECDSA-SHA256 too, so for an EC key the separation holds only for a signer that checks toBeSigned's length and label before signing, which this Gateway cannot verify of a caller's signer. 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	The signature over leg 1's toBeSigned bytes, base64: RSASSA-PSS/SHA-256/ MGF1-SHA-256/salt 32 for an RSA key, ECDSA/SHA-256 (DER) for an EC key.

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. Or CERTIFICATE_REVOKED (ADR 0115) -- the key server decides it before issuing the challenge, so in the ordinary sequence it arrives on leg 1; this leg relays every key-server refusal through the same classification, and it is listed so a client handles it wherever it lands.

403

PRINCIPAL_DISABLED. Or REVOCATION_STATUS_UNAVAILABLE or REVOCATION_EVIDENCE_STALE (ADR 0115) -- no current revocation evidence is held for the certificate's issuer under a policy that requires it; an operator imports a CRL, and the certificate itself was not refused. Decided before the challenge, as CERTIFICATE_REVOKED is, and listed here for the same reason.

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. Or CERTIFICATE_REVOKED (ADR 0115) -- the key server decides it before issuing the challenge, so in the ordinary sequence it arrives on leg 1; this leg relays every key-server refusal through the same classification, and it is listed so a client handles it wherever it lands.
403	PRINCIPAL_DISABLED. Or REVOCATION_STATUS_UNAVAILABLE or REVOCATION_EVIDENCE_STALE (ADR 0115) -- no current revocation evidence is held for the certificate's issuer under a policy that requires it; an operator imports a CRL, and the certificate itself was not refused. Decided before the challenge, as CERTIFICATE_REVOKED is, and listed here for the same reason.
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.