Display Tokens

Generated from core/api/router.go. Edit the router, not this file.

Method	Path	Who can call it
GET	/api/v1/display-tokens	Admin
POST	/api/v1/display-tokens	Admin
DELETE	/api/v1/display-tokens/:id	Admin

Create:

{ "name": "fourth-floor-corridor", "expires_in_days": 90 }

name is required and unique — it is what makes "revoke the screen by the lifts" an answerable request. expires_in_days defaults to 90 and is capped at 365; there is no unlimited option.

{
  "token": "cpd_...",
  "display": { "id": "...", "name": "...", "status": "ACTIVE", "expires_at": "..." },
  "warning": "This token is shown once and cannot be retrieved again. ..."
}

token appears in this response and nowhere else. Only its SHA-256 is stored, so a database dump yields no working credentials — and neither does the list endpoint, which returns everything except the hash.

status is ACTIVE, EXPIRED, or REVOKED. Revocation outranks expiry, and is a soft delete: the row survives with revoked_at and revoked_by set, because when a credential had to be pulled is exactly what someone will ask later.

See Authenticating an unattended screen for what the credential can and cannot do.

Endpoint detail

GET /api/v1/display-tokens

Who can call it	Admin
Handler	displayHandler.List
Display token	Refused — not a viewer-safe GET

Admin-only throughout: minting a credential that authenticates to the API is an administrative act even though what it grants is read-only.

Responses

Status	Body
200	An object with data, total
500	{ "error": … }

Example request

curl -X GET 'https://certpilot.example.com/api/v1/display-tokens' \
  -H 'Authorization: Bearer <token>'

POST /api/v1/display-tokens

Who can call it	Admin
Handler	displayHandler.Create
Display token	Refused — not a viewer-safe GET

Request body

Field	Type		Description
name	string	required
expires_in_days	integer		ExpiresInDays defaults to 90 and is capped at 365.

Responses

Status	Body
201	An object with display, token, warning (string)
400	{ "error": … } · a name is required — it is what identifies which screen to revoke
500	{ "error": … }

Example request

curl -X POST 'https://certpilot.example.com/api/v1/display-tokens' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "<name>",
  "expires_in_days": 0
}'

DELETE /api/v1/display-tokens/:id

Who can call it	Admin
Handler	displayHandler.Revoke
Display token	Refused — not a viewer-safe GET

Parameters

Name	In		Default
id	path	required

Responses

Status	Body
200	An object with message (string)
404	{ "error": … }

Example request

curl -X DELETE 'https://certpilot.example.com/api/v1/display-tokens/<id>' \
  -H 'Authorization: Bearer <token>'