On this page

Portal API reference

The management portal's API is an open specification, so that the offline portal and the TestifySec platform can serve the same contract. Paths are under /api/v1. The tenant comes from the deployment or the credential, never from the path. JSON request bodies refuse unknown fields. Errors are RFC 9457 application/problem+json documents whose error member holds a stable code.

Every route except discovery and the device routes requires a client certificate that the portal verifies against the enclave CA. The certificate subject identifies the user, and the role (admin, approver or auditor) comes from the portal's user directory.

The portal is on main. Operations marked "specified, not built" are part of the contract and have no implementation yet.

Generated from testifysec/portal/api/openapi.yaml: Badger management portal API, version 0.6.0, OpenAPI 3.1.0.

Method	Path	Status	Summary
GET	`/api/v1/profiles`	implemented	Latest signed version of every profile (admin, approver, auditor)
GET	`/api/v1/profiles/{profileId}/versions`	implemented	Every version of a profile, newest first, without envelopes (admin, approver, auditor)
POST	`/api/v1/profiles/{profileId}/versions`	implemented	Sign the next version (admin). The server assigns tenant and sequence.
GET	`/api/v1/profiles/{profileId}/trust`	implemented	Build-provisioned admission trust input for this profile (admin, auditor)
GET	`/api/v1/profiles/{profileId}/versions/{sequence}`	implemented	One version, without its envelope (admin, approver, auditor)
GET	`/api/v1/profiles/{profileId}/versions/{sequence}/envelope`	implemented	The DSSE envelope exactly as signed (admin, approver, auditor)
GET	`/api/v1/deployments/{deploymentId}/assignment`	implemented	The version a deployment (device group) runs (admin, approver, auditor)
PUT	`/api/v1/deployments/{deploymentId}/assignment`	implemented	Point a deployment at a signed version of its profile (admin)
GET	`/.well-known/badger-portal`	implemented	Discovery; public, names no tenant, deployment or key
GET	`/api/v1/users`	implemented	The user directory (admin, approver, auditor)
POST	`/api/v1/users`	implemented	Provision an identity the enclave PKI or IdP issued (admin). Pending, no role, until an approver activates it. Inviting a pending user with no open activation request issues one; otherwise 409.
POST	`/api/v1/users/{userId}/drop-role`	implemented	Remove an active user's role at once (admin); body {}
PUT	`/api/v1/users/{userId}/deployments/{deploymentId}`	implemented	Add an active user to a deployment (admin); body {}
DELETE	`/api/v1/users/{userId}/deployments/{deploymentId}`	implemented	Remove a membership (admin); body {}
POST	`/api/v1/users/{userId}/offboard`	implemented	Offboard (admin, not self); final. Clears role and memberships and drops pending requests by or about the user; body {}
GET	`/api/v1/role-requests`	implemented	The approver queue, pending requests only (admin, approver, auditor)
POST	`/api/v1/users/{userId}/role-requests`	implemented	Request a role for an active user (admin); nothing changes until an approver decides
POST	`/api/v1/role-requests/{requestId}/approve`	implemented	Approve (approver who is neither the requester nor the user)
POST	`/api/v1/role-requests/{requestId}/reject`	implemented	Reject (same rule as approve)
GET	`/api/v1/device/nonce`	specified, not built	One-use nonce for a device-key proof
POST	`/api/v1/device/profile`	specified, not built	A workstation pulls its signed profile, its deployment's activation record and any pending reset

GET /api/v1/profiles

Latest signed version of every profile (admin, approver, auditor)

Status: implemented. Authentication: client certificate (mutual TLS).

Response 200: Versions, without envelopes

application/json:

Field	Type	Required	Description
`items`	array of `Version`	yes

Response default: Error

application/problem+json: Problem

GET /api/v1/profiles/{profileId}/versions

Every version of a profile, newest first, without envelopes (admin, approver, auditor)

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`profileId`	path	`Identifier`	yes

Response 200: Versions

application/json:

Field	Type	Required	Description
`items`	array of `Version`	yes

Response default: Error

application/problem+json: Problem

POST /api/v1/profiles/{profileId}/versions

Sign the next version (admin). The server assigns tenant and sequence.

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`profileId`	path	`Identifier`	yes

Request body:

application/json:

Field	Type	Required
`deploymentId`	`Identifier`	yes
`notBefore`	`Instant`	yes
`expiresAt`	`Instant`	yes

Response 201: Signed and stored

application/json: Version

Response default: Error

application/problem+json: Problem

GET /api/v1/profiles/{profileId}/trust

Build-provisioned admission trust input for this profile (admin, auditor)

Exactly the schema testifysec/managed/README.md accepts; minimumSequence is the latest sequence.

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`profileId`	path	`Identifier`	yes

Response 200: Trust input

application/json:

Field	Type	Required
`schemaVersion`	`1`	yes
`publicKeys`	array of string (at least 1, at most 16)	yes
`threshold`	integer (minimum 1)	yes
`tenantId`	`Identifier`	yes
`deploymentId`	`Identifier`	yes
`profileId`	`Identifier`	yes
`minimumSequence`	`Sequence`	yes

Response default: Error

application/problem+json: Problem

GET /api/v1/profiles/{profileId}/versions/{sequence}

One version, without its envelope (admin, approver, auditor)

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`profileId`	path	`Identifier`	yes
`sequence`	path	string (pattern `^[1-9][0-9]{0,15}$`)	yes

Response 200: Version

application/json: Version

Response default: Error

application/problem+json: Problem

GET /api/v1/profiles/{profileId}/versions/{sequence}/envelope

The DSSE envelope exactly as signed (admin, approver, auditor)

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`profileId`	path	`Identifier`	yes
`sequence`	path	string (pattern `^[1-9][0-9]{0,15}$`)	yes

Response 200: Envelope bytes; sha256 equals the version's envelopeSha256

application/vnd.dsse.envelope.v1+json:

Field	Type	Required	Description

Response default: Error

application/problem+json: Problem

GET /api/v1/deployments/{deploymentId}/assignment

The version a deployment (device group) runs (admin, approver, auditor)

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`deploymentId`	path	`Identifier`	yes

Response 200: Assignment

application/json: Assignment

Response default: Error

application/problem+json: Problem

PUT /api/v1/deployments/{deploymentId}/assignment

Point a deployment at a signed version of its profile (admin)

Forward only. An older sequence, or a different profile once one is assigned, is 409 rollback; roll back by signing a new version.

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`deploymentId`	path	`Identifier`	yes

Request body:

application/json:

Field	Type	Required	Description
`profileId`	`Identifier`	yes
`sequence`	`Sequence`	yes

Response 200: Assignment

application/json: Assignment

Response default: Error

application/problem+json: Problem

GET /.well-known/badger-portal

Discovery; public, names no tenant, deployment or key

Status: implemented. Authentication: none.

Response 200: Discovery document

application/json:

Field	Type	Required
`specVersion`	string	yes
`apiBase`	string	yes
`profilePayloadType`	string	yes
`authentication`	array of `mutualTLS`	yes

GET /api/v1/users

The user directory (admin, approver, auditor)

Status: implemented. Authentication: client certificate (mutual TLS).

Response 200: Users

application/json:

Field	Type	Required	Description
`items`	array of `User`	yes

Response default: Error

application/problem+json: Problem

POST /api/v1/users

Provision an identity the enclave PKI or IdP issued (admin). Pending, no role, until an approver activates it. Inviting a pending user with no open activation request issues one; otherwise 409.

Status: implemented. Authentication: client certificate (mutual TLS).

Request body:

application/json:

Field	Type	Required	Description
`kind`	`x509`	yes
`subject`	string	yes	Certificate subject DN

Response 201: The pending user and its activation request

application/json:

Field	Type	Required	Description
`user`	`User`	yes
`activation`	`RoleRequest`	yes

Response default: Error

application/problem+json: Problem

POST /api/v1/users/{userId}/drop-role

Remove an active user's role at once (admin); body {}

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`userId`	path	`Digest`	yes

Response 200: User

application/json: User

Response default: Error

application/problem+json: Problem

PUT /api/v1/users/{userId}/deployments/{deploymentId}

Add an active user to a deployment (admin); body {}

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`userId`	path	`Digest`	yes
`deploymentId`	path	`Identifier`	yes

Response 200: User

application/json: User

Response default: Error

application/problem+json: Problem

DELETE /api/v1/users/{userId}/deployments/{deploymentId}

Remove a membership (admin); body {}

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`userId`	path	`Digest`	yes
`deploymentId`	path	`Identifier`	yes

Response 200: User

application/json: User

Response default: Error

application/problem+json: Problem

POST /api/v1/users/{userId}/offboard

Offboard (admin, not self); final. Clears role and memberships and drops pending requests by or about the user; body {}

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`userId`	path	`Digest`	yes

Response 200: User

application/json: User

Response default: Error

application/problem+json: Problem

GET /api/v1/role-requests

The approver queue, pending requests only (admin, approver, auditor)

Status: implemented. Authentication: client certificate (mutual TLS).

Response 200: Pending requests

application/json:

Field	Type	Required	Description
`items`	array of `RoleRequest`	yes

Response default: Error

application/problem+json: Problem

POST /api/v1/users/{userId}/role-requests

Request a role for an active user (admin); nothing changes until an approver decides

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`userId`	path	`Digest`	yes

Request body:

application/json:

Field	Type	Required	Description
`role`	`admin`, `approver`, `auditor`	yes

Response 201: Request

application/json: RoleRequest

Response default: Error

application/problem+json: Problem

POST /api/v1/role-requests/{requestId}/approve

Approve (approver who is neither the requester nor the user)

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`requestId`	path	string (pattern `^[0-9a-f]{32}$`)	yes

Response 200: Request

application/json: RoleRequest

Response default: Error

application/problem+json: Problem

POST /api/v1/role-requests/{requestId}/reject

Reject (same rule as approve)

Status: implemented. Authentication: client certificate (mutual TLS).

Parameter	In	Type	Required
`requestId`	path	string (pattern `^[0-9a-f]{32}$`)	yes

Response 200: Request

application/json: RoleRequest

Response default: Error

application/problem+json: Problem

GET /api/v1/device/nonce

One-use nonce for a device-key proof

Status: specified, not built. Authentication: none.

Response 200: Nonce, valid for 60 seconds

application/json:

Field	Type	Required	Description
`nonce`	string	yes

POST /api/v1/device/profile

A workstation pulls its signed profile, its deployment's activation record and any pending reset

The device proves possession of its cilock-enrolled device key (TPM or Secure Enclave custody): proof is a compact ES256 JWS by that key over the nonce, the key thumbprint and this portal's audience. Returns both documents exactly as signed for the device's deployment. 403 when unknown or revoked. The portal never pushes.

Status: specified, not built. Authentication: none.

Request body:

application/json:

Field	Type	Required	Description
`nonce`	string	yes
`proof`	string	yes

Response 200: The current pair

application/json:

Field	Type	Required	Description
`envelope`	object	yes	Profile DSSE envelope
`activation`	object	yes	Activation record DSSE envelope
`reset`	object	no	Pending device-bound high-water reset record (DSSE), present only when one awaits this device

Response default: Error

application/problem+json: Problem

Schemas

User

Field	Type	Required
`id`	`Digest`	yes
`kind`	`x509`	yes
`subject`	string	yes
`role`	``, `admin`, `approver`, `auditor`	yes
`status`	`pending`, `active`, `offboarded`	yes
`createdAt`	string (date-time)	yes
`createdBy`	string	yes
`deployments`	array of `Identifier`	no

RoleRequest

Field	Type	Required
`id`	string	yes
`kind`	`activate`, `grant`	yes
`userId`	`Digest`	yes
`role`	``, `admin`, `approver`, `auditor`	yes
`requestedBy`	string	yes
`requesterId`	`Digest`	yes
`requestedAt`	string (date-time)	yes
`status`	`pending`, `approved`, `rejected`, `dropped`	yes
`decidedBy`	string	no
`decidedAt`	string (date-time)	no

Assignment

Field	Type	Required
`deploymentId`	`Identifier`	yes
`profileId`	`Identifier`	yes
`sequence`	`Sequence`	yes
`payloadSha256`	`Digest`	yes
`assignedAt`	string (date-time)	yes
`assignedBy`	string	yes

Identifier

string (pattern ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$)

Instant

string (pattern ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$)

Sequence

integer (minimum 1, maximum 9007199254740991)

Digest

string (pattern ^[0-9a-f]{64}$)

Version

Field	Type	Required	Description
`profileId`	`Identifier`	yes
`tenantId`	`Identifier`	yes
`deploymentId`	`Identifier`	yes
`sequence`	`Sequence`	yes
`notBefore`	`Instant`	yes
`expiresAt`	`Instant`	yes
`payloadSha256`	`Digest`	yes
`envelopeSha256`	`Digest`	yes
`signerKeyIds`	array of `Digest`	yes
`createdAt`	string (date-time)	yes
`createdBy`	string	yes	Authenticated principal (certificate subject DN or OIDC subject)

Problem

RFC 9457 problem document; "error" repeats the stable code.

Field	Type	Required
`type`	string	yes
`title`	string	yes
`status`	integer	yes
`detail`	string	no
`error`	`unauthenticated`, `forbidden`, `cross-origin`, `invalid-request`, `invalid-profile`, `sequence-conflict`, `rollback`, `not-found`, `store`, `issue-failed`, `assign-failed`, `conflict`, `invalid-state`, `users-failed`	yes

Reference generated from the product documentation. Match commands and support details to your installed release.