Discovery API Reference

DRAFT — Internal Developer Use Only

This API reference is for internal development teams. It is not yet published for external consumption.

Overview

What it is: The Hydden Discovery platform exposes a REST API for programmatic access to identity discovery, collection, automation, and governance features. Other Hydden products such as Control use these endpoints to synchronize identity data.

Why it matters: Internal developers who build integrations between Hydden products need a clear reference for available endpoints, authentication methods, and data formats.

Base URLs

Discovery organizes its API into two route groups:

Route prefix	Purpose	Authentication
/api/v1/	Public API — external integrations and cross-product calls	JWT cookie + API token + CORS
/internal/v1/	Internal API — platform management and configuration	JWT cookie + API token + CORS

Both prefixes require authentication. The /api/v1/ prefix is the primary integration surface for other Hydden products.

Authentication

Hydden supports three authentication methods. See the Authentication reference for full details.

Method	Endpoint	Use case
API credentials	POST /auth/api	Service-to-service calls (e.g., Control syncing data)
One-time password	POST /auth/otp	Short-lived interactive sessions
OAuth 2.0	POST /oauth/token	Standard OAuth flows with Basic Auth header

Token format: All methods return a bearer token. Include it in subsequent requests:

GET /api/v1/dashboard/status
Authorization: Bearer <token>

How Control authenticates: Hydden Control uses POST /auth/api with a ClientID and ClientSecret pair stored in encrypted integration settings. The token is cached per tenant and refreshed automatically before expiry. See Control Integration Patterns below.

API Modules

Module	Path prefix	Description
Authentication	/auth/, /oauth/	Token generation and OIDC provider management
Identity	/internal/v1/entity/, /internal/v1/collector/	Entity queries, collector configs, connector templates
Automation	/api/v1/actions, /api/v1/workflows	Actions, workflows, triggers, and credentials
AI	/internal/v1/ai/	AI autocomplete, agent sessions, vector store
Attestation	/internal/v1/attest/	Certifications, attestation settings and types
Search	/api/v1/global/	SSRM query and global search endpoints
Dashboard	/api/v1/dashboard/	Dashboard status and account metadata
Vault	/internal/v1/vault/	Credential safe handlers and account management
Universal Connector	/internal/v1/connector/universal/	Custom connector schemas and mappings
System	/internal/v1/registry/, /internal/v1/license/	Registry, licensing, audit, datastore, notifications

Middleware Stack

Every request passes through these middleware layers (applied in order):

Diagram description: A top-down flow diagram showing the API middleware stack. A client request passes sequentially through the Request Logger, CORS Handler, JWT Cookie Auth, API Authenticator, and Compressor before reaching the Route Handler.

1. Request Logger — Captures metrics for monitoring
2. CORS Handler — Validates cross-origin requests
3. JWT Cookie — Extracts and validates JWT from cookies
4. API Authenticator — Validates API key or Bearer token
5. Compressor — Compresses responses (gzip, deflate, br)

Common Response Patterns

Success response:

{
  "data": { ... },
  "totalCount": 150,
  "viewTime": "2026-02-12T10:00:00Z"
}

Error response:

{
  "error": "unauthorized",
  "message": "Invalid or expired token",
  "code": 401
}

Standard HTTP status codes:

Code	Meaning
200	Success
201	Created
204	No content (successful delete)
400	Bad request — check request body
401	Unauthorized — token missing or expired
403	Forbidden — insufficient permissions
404	Not found
429	Rate limited — retry with backoff
500	Internal server error

Pagination

Endpoints that return lists support server-side pagination via request body:

{
  "offset": 0,
  "limit": 100,
  "filterModel": {},
  "sortModel": [],
  "rowGroupCols": [],
  "groupKeys": []
}

The response includes totalCount to calculate the number of pages.

Control Integration Patterns

Hydden Control integrates with Discovery through a dedicated HTTP client. Key patterns:

Aspect	Detail
Authentication	POST /auth/api with ClientID + encrypted ClientSecret per tenant
Token caching	Per-tenant token cache with automatic refresh before expiry
Retry logic	Exponential backoff for HTTP 429, 502, 503, 504 (max 3 retries)
Compression	Requests accept gzip, deflate, and brotli
User-Agent	Hydden-LiteIGA/1.0
Pagination	POST body with offset and limit, iterates until totalCount reached
Tenant isolation	Every call scoped to a single tenant via context-based settings lookup

Diagram description: A sequence diagram showing how Control integrates with the Discovery API. The Control Backend authenticates with Discovery via POST /auth/api using a ClientID and Secret, receives a Bearer token that is cached per tenant, then posts an SSRM query to retrieve columns, rows, and totalCount. Control maps Discovery fields to its own models and stores the data in a local repository.

Using Postman or Other API Clients

To access the complete interactive API reference, navigate to your portal's OpenAPI page:

https://<your-portal>.hydden.com/openapi/index.html

To create an API token for authentication, see API Tokens.