POST /api/v1/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. 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, as hex.
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_RETIRED -- decided on leg 1 like the two above; listed here for the same reason CERTIFICATE_REVOKED is. Or CERTIFICATE_REVOKED -- 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 -- 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.

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.

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.

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_RETIRED -- decided on leg 1 like the two above; listed here for the same reason CERTIFICATE_REVOKED is. Or CERTIFICATE_REVOKED -- 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 -- 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.
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.
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.