cdnca

API reference

/v1/admin/inbox

4 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
GET/v1/admin/inboxList the platform administrator's messages, newest firstSession
POST/v1/admin/inbox/read-allMark all the caller's messages read (audited admin.inbox.read_all); read messages older than 180 days are prunedSession
GET/v1/admin/inbox/unread-countUnread message count for the header badgeSession
POST/v1/admin/inbox/{message_id}/readMark one message readSession

Contract file：api/openapi/v1/control.yaml

Operation details

GET /v1/admin/inbox

List the platform administrator's messages, newest first

operationId
listAdminInbox
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

Platform operations events addressed to the caller (node offline/recovered, ACME HTTP-01 epoch drift, staff ticket events). Every platform-scope session reads only its own messages. params holds the event's public template values; the console renders the text per language.

Parameters

listAdminInbox Parameters
NameInTypeRequiredDescription
unreadquerystring: trueNo—
page_sizequeryintegerNo—
cursorquerystringNo—

Responses

listAdminInbox Responses
StatusDescription
200One page.

Fields：items: array<object> unread: integer total: integer next_cursor: string unread_only: boolean page_size: integer

401Authentication failed or the session is invalid.
403The authenticated principal is not allowed to perform the action.

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.

↑ Back to list

POST /v1/admin/inbox/read-all

Mark all the caller's messages read (audited admin.inbox.read_all); read messages older than 180 days are pruned

operationId
markAllAdminInboxMessagesRead
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Responses

markAllAdminInboxMessagesRead Responses
StatusDescription
200Number of messages marked.

Fields：marked: integer

↑ Back to list

GET /v1/admin/inbox/unread-count

Unread message count for the header badge

operationId
getAdminInboxUnreadCount
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Responses

getAdminInboxUnreadCount Responses
StatusDescription
200Count.

Fields：unread: integer

401Authentication failed or the session is invalid.

What to do on failure

  • 401 Check the credential format and whether it expired or was rotated.

↑ Back to list

POST /v1/admin/inbox/{message_id}/read

Mark one message read

operationId
markAdminInboxMessageRead
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

markAdminInboxMessageRead Parameters
NameInTypeRequiredDescription
message_idpathstring(uuid)Yes—

Responses

markAdminInboxMessageRead Responses
StatusDescription
204Read.
404admin_inbox_message_not_found (not the caller's message).

What to do on failure

  • 404 The resource does not exist or belongs to another tenant.

↑ Back to list