API reference · Enrolment

Submit a public key

POST/v1/enrollments/{invitationId}/keys

Sends the PUBLIC half of a new P-256 key, and receives the challenge to prove you hold the private half.

PermissionNone

AuthenticationEnrolment token

Anis’s answerSigned

Staff-set limits it counts towardNone

.NET SDKenrollment.SubmitKeyAsync(request)

Save the private key before you call this: an invitation takes exactly one key.
The answer carries safetyCode. Anis staff will phone your technical contact and ask you to read it before your key goes live.

Parameters

Name	In	Type	Notes
`invitationId`required	`path`	UUID	A UUID, lower-case with hyphens.

Request

Authorised with Authorization: Enrollment <token>; not signed.

Headers: Accept-Language (optional). The SDKs set all of them for you.

Body: EnrollmentKeyRequest, as JSON.

Field	Type	Notes
`publicJwk`required	PublicJwk	The PUBLIC half of a new P-256 key only. A private member is refused.
`notBefore`required	string (date-time)	Only the length of the window (to `expiresAt`) is used, and it starts when Anis staff activate the key. Anis keeps the shorter of the validity you ask for and the validity Anis staff set (never more than two years).
`expiresAt`required	string (date-time)	The end of the validity you ask for. See `notBefore`.

Responses

Status	Meaning	Body
200	Success.	EnrollmentKeyResult
401	Refused: not authenticated.	Problem
404	Refused: not found, or not yours.	Problem
409	Refused: conflicts with the current state.	Problem
422	Refused: the request breaks a rule.	Problem
429	Refused: a limit was reached.	Problem
503	No decision: a dependency was unavailable.	Problem

Every answer of this call is signed by Anis — success and every refusal. Require the signature and verify it before you act on the answer; an answer without one is a failure, never an answer (how).

Refusals

Every refusal of this call is a signed problem. Branch on its code; each links to what it means and what to do.

Error	Code	Status
Invitation invalid	`invitation_invalid`	401
Not found	`resource_not_found`	404
Validation failed	`validation_failed`	422
Public key invalid	`key_proof_invalid`	422
Invitation already used	`key_duplicate`	409
Rate limited	`rate_limited`	429
Service unavailable	`dependency_unavailable`	503
Request timeout	`request_timeout`	504
Internal error	`internal_error`	500

Types

EnrollmentKeyRequest

Field	Type	Notes
`publicJwk`required	PublicJwk	The PUBLIC half of a new P-256 key only. A private member is refused.
`notBefore`required	string (date-time)	Only the length of the window (to `expiresAt`) is used, and it starts when Anis staff activate the key. Anis keeps the shorter of the validity you ask for and the validity Anis staff set (never more than two years).
`expiresAt`required	string (date-time)	The end of the validity you ask for. See `notBefore`.

PublicJwk

Field	Type	Notes
`kty`required	string	Always `EC`. Values: `EC`
`crv`required	string	Always `P-256`. Values: `P-256`
`x`required	string	The key’s x coordinate: exactly 32 bytes, base64url without padding.
`y`required	string	The key’s y coordinate: exactly 32 bytes, base64url without padding.
`kid`	string	In Anis’s signing keys: the key an answer’s signature names. Treat it as an opaque name. Not sent when you submit your own key.
`use`	string	Intended use, when published.
`alg`	string	Algorithm, when published.

EnrollmentKeyResult

Field	Type	Notes
`keyId`always present	UUID	Your key id: the `keyid` every signature will carry once the key is active.
`thumbprint`always present	string	The key’s fingerprint (RFC 7638). Part of the proof message you sign.
`safetyCode`always present	string	The 16-character safety code derived from your key’s fingerprint, written `XXXX-XXXX-XXXX-XXXX`. Anis staff will phone your technical contact and ask you to read it before your key goes live.
`challenge`always present	string	The challenge your proof answers. It is returned only here: keep it until the proof is accepted.
`challengeGeneration`	integer	Which challenge this is; a restarted enrolment issues the next one.