Attestation & Certifications API

DRAFT — Internal Developer Use Only

This API reference is for internal development teams.

Overview

What it is: The attestation API manages certification campaigns, attestation settings, and compliance review workflows. Certifications verify that identity access is appropriate and approved.

Why it matters: Hydden Control's access review campaigns depend on Discovery's attestation endpoints to create certifications, retrieve records, and track compliance status.

Certification Endpoints

Method	Path	Description	Auth required
POST	/internal/v1/attest/certification	Create or update a certification	JWT + API token
GET	/internal/v1/attest/certification	List certifications	JWT + API token
GET	/internal/v1/attest/certification/:ctx/:type/:id	Get a specific certification	JWT + API token
GET	/internal/v1/attest/certification/:ctx/:type/:id/columns	Get available columns for a certification	JWT + API token
GET	/internal/v1/attest/certification/:ctx/:type/:id/records/:source/:entity_type	Stream certification records	JWT + API token

Settings Endpoints

Method	Path	Description	Auth required
POST	/internal/v1/attest/settings	Create or update attestation settings	JWT + API token
GET	/internal/v1/attest/settings	List all settings	JWT + API token
GET	/internal/v1/attest/settings/:ctx/:type	Get settings for a specific context and type	JWT + API token
DELETE	/internal/v1/attest/settings/:ctx/:type	Delete settings	JWT + API token

Reference Endpoints

Method	Path	Description	Auth required
GET	/internal/v1/attest/types	List certification types	JWT + API token
GET	/internal/v1/attest/statuses	List certification statuses	JWT + API token

---

Certification Types

GET /internal/v1/attest/types
Authorization: Bearer <token>

Response (200):

{
  "attestation.certification.collector": {
    "name": "Identity Integrity",
    "description": "Ensures the integrity of identity data collected by specified collectors."
  },
  "attestation.certification.schema": {
    "name": "Schema Integrity",
    "description": "Validates that schema definitions used in identity data collection are up-to-date and accurate."
  },
  "attestation.certification.report": {
    "name": "Report Integrity",
    "description": "Certifies that scheduled report results have been reviewed and approved."
  }
}

Certification Statuses

GET /internal/v1/attest/statuses
Authorization: Bearer <token>

Response (200):

[
  { "value": "pending",     "name": "Pending",     "description": "Certification is awaiting assignment or action" },
  { "value": "in_progress", "name": "In Progress", "description": "Certification is currently being reviewed" },
  { "value": "completed",   "name": "Completed",   "description": "Certification has been successfully completed" },
  { "value": "abandoned",   "name": "Abandoned",   "description": "Certification has been abandoned" }
]

---

POST /internal/v1/attest/certification

Create or update a certification. Updating a closed certification returns 409 errAlreadyClosed.

Certification fields:

Field	Type	Description
id	string	ULID — required on all requests; generate client-side using a ULID library
context_id	string	Collector or saved-search identifier
type	string	Certification type key (see Certification Types)
title	string	Display name
assigned_to	string	Entity string of the reviewer (grid.user:<id>)
status	string	Target status (see Status transitions)
priority	string	low, medium, high, or critical
due_date	int64	Unix timestamp in milliseconds
activity	array	Activity entries to append
actions.unassign	boolean	Set to true to remove the current assignee

Request (create):

POST /internal/v1/attest/certification
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "01JQ2MK4TPXE3R7FQNZ8VYG5H2",
  "context_id": "collector-uuid-001",
  "type": "attestation.certification.collector",
  "title": "Q1 2026 Identity Integrity Review",
  "assigned_to": "grid.user:user-uuid-001",
  "priority": "high",
  "due_date": 1751328000000
}

Response (200): Returns the updated certification JSON string.

Status Transitions

From	To	Condition
pending	in_progress	Assigned user submits any update (automatic)
Any	pending	Certification is reassigned
in_progress	completed	Assigned user explicitly sets status
Any open	abandoned	Any user explicitly sets status
completed or abandoned	—	Closed; returns 409 errAlreadyClosed on any update

---

GET /internal/v1/attest/certification

List certifications visible to the authenticated user.

Query parameters:

Parameter	Type	Default	Description
tombstoned	boolean	false	Include closed (completed or abandoned) certifications
source	string	—	Filter by collector or saved-search context ID

Role behavior:

• Owner — sees all certifications across all contexts.
• Other users — see only certifications assigned to them.

Request:

GET /internal/v1/attest/certification?tombstoned=true&source=collector-uuid-001
Authorization: Bearer <token>

Response (200):

[
  {
    "id": "01JDKM5X...",
    "context_id": "collector-uuid-001",
    "type": "attestation.certification.collector",
    "title": "Q4 2025 Identity Integrity Review",
    "assigned_to": "grid.user:user-uuid-001",
    "status": "completed",
    "priority": "high",
    "closed": true,
    "opened_at": "2025-12-01T09:00:00Z",
    "closed_at": "2025-12-15T14:22:00Z"
  }
]

---

GET /internal/v1/attest/certification/:ctx/:type/:id

Get a single certification by context, type, and ID.

Path parameters:

Parameter	Description
ctx	Collector or saved-search context ID
type	URL-encoded certification type key
id	Certification ULID

Request:

GET /internal/v1/attest/certification/collector-uuid-001/attestation.certification.collector/01JDKM5X...
Authorization: Bearer <token>

Response (200): Returns the full Certification object including activity, content, and timestamps.

---

GET /internal/v1/attest/certification/:ctx/:type/:id/columns

Get available data sources and entity types for a certification. Used by the review UI to build the source and entity type dropdowns.

Request:

GET /internal/v1/attest/certification/collector-uuid-001/attestation.certification.collector/01JDKM5X.../columns
Authorization: Bearer <token>

Response (200):

{
  "ds-uuid-001": {
    "principal.account": [
      { "field": "name", "headerName": "Name" },
      { "field": "email", "headerName": "Email" },
      { "field": "department", "headerName": "Department" }
    ]
  },
  "ds-uuid-002": {
    "principal.account": [
      { "field": "name", "headerName": "Name" }
    ]
  }
}

---

GET /internal/v1/attest/certification/:ctx/:type/:id/records/:source/:entity_type

Stream identity records for a certification, data source, and entity type. The response is chunked JSON containing columns and record rows.

Path parameters:

Parameter	Description
ctx	Collector context ID
type	URL-encoded certification type key
id	Certification ULID
source	Data source identifier
entity_type	Entity type (e.g., principal.account)

Request:

GET /internal/v1/attest/certification/collector-uuid-001/attestation.certification.collector/01JDKM5X.../records/ds-uuid-001/principal.account
Authorization: Bearer <token>

Response (200):

{
  "columns": [
    { "field": "name", "headerName": "Name" },
    { "field": "email", "headerName": "Email" }
  ],
  "records": [
    { "name": "jdoe", "email": "jdoe@example.com" },
    { "name": "asmith", "email": "asmith@example.com" }
  ]
}

Notes:

• Response uses Transfer-Encoding: chunked. Consume it as a stream for large datasets.
• Records are returned raw from the attestation store. Apply filtering and sorting client-side if needed.

Export Options

The review UI exports certification records as CSV using the grid's current column state. The export:

• Includes all columns (visible and hidden) using exportDataAsCsv({ allColumns: true }).
• Uses the filename format Certification_{collector_name}_{entity_type}.csv.
• Logs an export activity entry on the certification when the dialog is closed.

For server-side export, call the records endpoint and serialize the records array to CSV. Apply the columns array from the response as headers.

---

Scheduled Certifications

Certifications can run automatically on a cron schedule. Assign a schedule to attestation settings for a collector to trigger recurring certification campaigns.

Schedule behavior:

• Timezone-aware schedules are supported.
• Certifications for tombstoned or unreachable collectors are automatically skipped.
• The scheduler seeds the next-run time from the most recently completed certification to avoid duplicate runs on restart.
• Schedule changes take effect on the next scheduled run.

Settings fields for scheduling:

Field	Type	Description
schedule	string	ID of a configured cron schedule
context_id	string	Collector context identifier
type	string	Certification type key

Request (set schedule):

POST /internal/v1/attest/settings
Authorization: Bearer <token>
Content-Type: application/json

{
  "context_id": "collector-uuid-001",
  "type": "attestation.certification.collector",
  "schedule": "schedule-uuid-001"
}

---

Attestation Settings — Column State

The column_state field on settings persists the review UI grid state (column visibility, order, widths, sort, and filter) per entity type. The key is the entity type string; the value is an AG Grid column state array.

{
  "context_id": "collector-uuid-001",
  "type": "attestation.certification.collector",
  "column_state": {
    "principal.account": [
      { "colId": "name", "hide": false, "width": 200, "sort": "asc", "sortIndex": 0 },
      { "colId": "email", "hide": false, "width": 300 }
    ]
  }
}

Column state is saved automatically with a 1-second debounce after any grid interaction (column move, resize, visibility change, sort, or filter).

---

Control Integration

Hydden Control creates and manages certification campaigns through these endpoints as part of its access review workflow. Control's campaign rules engine determines the scope and schedules for certifications.