certification-status

16 endpoints.

GET/api/certifications/status Bearer token

Evaluate certification status

Evaluates every certification requirement of a user: the types their unexpired role grants require, the current award, the due date, and per-rule progress since the current award. Any bearer user may read their own status; reading another user's requires certifications:read, and returns only types in the caller's scope.

Parameters

Name	In	Type	Required	Description
user	query	string (uuid)	no	Evaluate this user (`users.id`) instead of the caller. Requires certifications:read; the result is filtered to types in the caller's scope.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).

Responses

Status	Description	Body
200	The user's evaluated certification requirements.	UserCertificationStatusList
400	The org filter did not resolve.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	Another user was asked for without certifications:read.	ErrorResponse
500	The database could not be read.	ErrorResponse

POST/api/certifications/{cert_id}/claim Bearer token

Claim an automatic certification

Awards the caller a certification of an automatic-mode type they are required to hold, after the server re-validates that every proof rule is satisfied. Answers 409 when a rule is not met, or when the current award changed under the claim (retry after re-reading status).

Parameters

Name	In	Type	Required	Description
cert_id	path	string (uuid)	yes	UUID id of the certification type.

Responses

Status	Description	Body
201	The new award.	CertificationAward
400	The type is awarded by approval — file a request instead.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	No unexpired role grant of the caller requires this type.	ErrorResponse
404	That certification type does not exist, or is archived.	ErrorResponse
409	A proof rule is not satisfied, or the current award changed underneath.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/certifications/{cert_id}/request Bearer token

Request a certification

Files a request for an approval-mode type the caller is required to hold, to be decided by a holder of certifications:write. One pending request per user and type. An automatic type accepts a request too when it carries a manual_sign_off rule: the request asks a certifier for the sign-off (recorded from the approvals queue), after which the certifier approves the request or the caller claims the type themselves.

Parameters

Name	In	Type	Required	Description
cert_id	path	string (uuid)	yes	UUID id of the certification type.

Request body

application/jsonoptionalRequestCertificationRequest

Field	Type	Required	Description
message	string	no	Optional note to whoever decides the request. at most 2000 characters

Field

Type

Required

Description

message

string

Optional note to whoever decides the request.

at most 2000 characters

Responses

Status	Description	Body
201	The filed request.	CertificationRequest
400	The type is automatic with no sign-off rule — claim it instead.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	No unexpired role grant of the caller requires this type.	ErrorResponse
404	That certification type does not exist, or is archived.	ErrorResponse
409	A request is already pending, or the caller is not in the organization's directory.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/certification-requests/{request_id}/withdraw Bearer token

Withdraw an own request

Withdraws the caller's own still-pending request.

Parameters

Name	In	Type	Required	Description
request_id	path	string (uuid)	yes	UUID id of the certification request.

Responses

Status	Description	Body
200	The withdrawn request.	CertificationRequest
401	The access token is missing or invalid.	ErrorResponse
404	No request of the caller has that id.	ErrorResponse
409	The request has already been decided.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/certification-requests/{request_id}/approve Bearer token

Approve a request

Approves a pending request: inserts the award and stamps the request in one transaction. The deciding human is the authority — rules are not re-checked. Requires certifications:write over the type's owner.

Parameters

Name	In	Type	Required	Description
request_id	path	string (uuid)	yes	UUID id of the certification request.

Request body

application/jsonoptionalDecideCertificationRequestRequest

Field	Type	Required	Description
decision_note	string	no	Optional note recorded with the decision, shown to the requester. at most 2000 characters

Field

Type

Required

Description

decision_note

string

Optional note recorded with the decision, shown to the requester.

at most 2000 characters

Responses

Status	Description	Body
200	The approved request, with the resulting award's id.	CertificationRequest
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this request but does not hold certifications:write.	ErrorResponse
404	No visible request has that id.	ErrorResponse
409	The request has already been decided or withdrawn.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

POST/api/certification-requests/{request_id}/reject Bearer token

Reject a request

Rejects a pending request. Requires certifications:write over the type's owner.

Parameters

Name	In	Type	Required	Description
request_id	path	string (uuid)	yes	UUID id of the certification request.

Request body

application/jsonoptionalDecideCertificationRequestRequest

Field	Type	Required	Description
decision_note	string	no	Optional note recorded with the decision, shown to the requester. at most 2000 characters

Field

Type

Required

Description

decision_note

string

Optional note recorded with the decision, shown to the requester.

at most 2000 characters

Responses

Status	Description	Body
200	The rejected request.	CertificationRequest
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this request but does not hold certifications:write.	ErrorResponse
404	No visible request has that id.	ErrorResponse
409	The request has already been decided or withdrawn.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/certification-requests Bearer token

List certification requests

The approvals queue: requests whose certification type the caller holds certifications:write over, newest first, with cursor pagination. Defaults to pending requests only.

Parameters

Name	In	Type	Required	Description
status	query	string	no	Filter requests by status. Defaults to pending — the open queue.
org	query	string	no	Organization UUID id or slug to filter by (and to resolve slug refs in).
limit	query	integer	no	Page size, 1-200. Defaults to 50.
cursor	query	string	no	Opaque cursor from a previous page's next_cursor.

Responses

Status	Description	Body
200	One page of requests, and the cursor for the next.	CertificationRequestList
400	The org filter did not resolve, or the cursor is malformed.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
500	The database could not be read.	ErrorResponse

POST/api/certifications/{cert_id}/grants Bearer token

Grant a certification directly

Awards a certification to a user without a request — for paper history, external audits, or admin discretion. `awarded_at` may be backdated; the recert clock counts from it. Requires certifications:write over the type's owner.

Parameters

Name	In	Type	Required	Description
cert_id	path	string (uuid)	yes	UUID id of the certification type.

Request body

application/jsonrequiredGrantCertificationRequest

Field	Type	Required	Description
user_id	string (uuid)	yes	`users.id` of the user the certification is granted to.
awarded_at	string (date-time)	no	Omit for now; set to backdate a grant, e.g. one imported from paper.

Responses

Status	Description	Body
201	The new award.	CertificationAward
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this type but does not hold certifications:write.	ErrorResponse
404	No visible certification type has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/certifications/{cert_id}/awards Bearer token

List a type's awards

Lists the award events of one certification type, newest first, revoked ones included. Requires certifications:read over the type's owner.

Parameters

Name	In	Type	Required	Description
cert_id	path	string (uuid)	yes	UUID id of the certification type.
limit	query	integer	no	Page size, 1-200. Defaults to 50.

Responses

Status	Description	Body
200	The most recent awards of the type.	CertificationAwardList
401	The access token is missing or invalid.	ErrorResponse
404	No visible certification type has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

POST/api/certification-awards/{award_id}/revoke Bearer token

Revoke an award

Revokes one award. The row stays as history; the user's status reverts to outstanding (or to their previous unrevoked award). Requires certifications:write over the type's owner.

Parameters

Name	In	Type	Required	Description
award_id	path	string (uuid)	yes	UUID id of the award.

Responses

Status	Description	Body
200	The revoked award.	CertificationAward
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this award but does not hold certifications:write.	ErrorResponse
404	No visible award has that id.	ErrorResponse
409	The award is already revoked.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/certifications/{cert_id}/due-dates Bearer token

List a type's initial due dates

Lists the admin-set per-person initial due dates of one certification type, soonest first. Requires certifications:read over the type's owner.

Parameters

Name	In	Type	Required	Description
cert_id	path	string (uuid)	yes	UUID id of the certification type.

Responses

Status	Description	Body
200	The type's due dates.	CertificationDueDateList
401	The access token is missing or invalid.	ErrorResponse
404	No visible certification type has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

PUT/api/certifications/{cert_id}/due-dates/{user_id} Bearer token

Set a member's initial due date

Sets (or replaces) when one organization member's initial certification falls due, overriding any role-level initial due date. Requires certifications:write over the type's owner. The member must be in the organization's directory.

Parameters

Name	In	Type	Required	Description
cert_id	path	string (uuid)	yes	UUID id of the certification type.
user_id	path	string (uuid)	yes	`users.id` of the organization member.

Request body

application/jsonrequiredSetCertificationDueDateRequest

Field	Type	Required	Description
initial_due_at	string (date-time)	yes	When this user's initial certification falls due. Takes precedence over any role-level initial due date, earlier or later alike.

Responses

Status	Description	Body
200	The stored due date.	CertificationDueDate
400	The request body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this type but does not hold certifications:write.	ErrorResponse
404	No visible certification type has that id, or the user is not in the organization's directory.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/certifications/{cert_id}/due-dates/{user_id} Bearer token

Clear a member's initial due date

Clears a member's per-person initial due date; their requirement falls back to the role-level initial due date, or shows "No due date set" when no role sets one. Requires certifications:write over the type's owner.

Parameters

Name	In	Type	Required	Description
cert_id	path	string (uuid)	yes	UUID id of the certification type.
user_id	path	string (uuid)	yes	`users.id` of the organization member.

Responses

Status	Description	Body
200	The removed due date.	CertificationDueDate
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this type but does not hold certifications:write.	ErrorResponse
404	No visible certification type has that id, or no due date was set.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

GET/api/certification-rules/{rule_id}/sign-offs Bearer token

List a rule's sign-offs

Lists the sign-offs recorded against one rule, newest first, optionally for one user. Requires certifications:read over the type's owner.

Parameters

Name	In	Type	Required	Description
rule_id	path	string (uuid)	yes	UUID id of the proof rule.
user	query	string (uuid)	no	Evaluate this user (`users.id`) instead of the caller. Requires certifications:read; the result is filtered to types in the caller's scope.

Responses

Status	Description	Body
200	The rule's sign-offs.	CertificationSignOffList
401	The access token is missing or invalid.	ErrorResponse
404	No visible rule has that id.	ErrorResponse
500	The database could not be read.	ErrorResponse

POST/api/certification-rules/{rule_id}/sign-offs Bearer token

Record a sign-off

Records that a user satisfies one manual_sign_off rule. `signed_off_at` may be backdated; a renewal needs a sign-off after the current award. Requires certifications:write over the type's owner.

Parameters

Name	In	Type	Required	Description
rule_id	path	string (uuid)	yes	UUID id of the proof rule.

Request body

application/jsonrequiredCreateCertificationSignOffRequest

Field	Type	Required	Description
user_id	string (uuid)	yes	`users.id` of the user being signed off.
signed_off_at	string (date-time)	no	Omit for now; set to backdate a sign-off.
note	string	no	at most 2000 characters

Responses

Status	Description	Body
201	The recorded sign-off.	CertificationSignOff
400	The rule is not a manual_sign_off rule, or the body failed validation.	ErrorResponse
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this rule but does not hold certifications:write.	ErrorResponse
404	No visible rule has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse

DELETE/api/certification-sign-offs/{sign_off_id} Bearer token

Delete a sign-off

Hard-deletes a mistaken sign-off, the way evidence is deleted. Requires certifications:write over the type's owner.

Parameters

Name	In	Type	Required	Description
sign_off_id	path	string (uuid)	yes	UUID id of the sign-off.

Responses

Status	Description	Body
200	The deleted sign-off.	CertificationSignOff
401	The access token is missing or invalid.	ErrorResponse
403	The caller can read this sign-off but does not hold certifications:write.	ErrorResponse
404	No visible sign-off has that id.	ErrorResponse
500	The database could not be reached, or the write failed.	ErrorResponse