Registry Configuration API

DRAFT — Internal Developer Use Only

This API reference is for internal development teams.

Overview

What it is: The Registry Configuration API is the central configuration store for Hydden Discovery. It provides CRUD operations for three configuration scopes — system config, user config, and module config — each with its own namespace. All configurations use a versioned, replicated storage model with soft-delete (tombstone) and hard-delete (erase) semantics.

Source: src/registry/rest/rest.go

Base Path

/internal/v1/registry

Authentication

All endpoints require JWT cookie or API token authentication.

Configuration Scopes

Scope	Path Prefix	Description
Config	`/internal/v1/registry/config/:entity`	System-level configuration (collectors, workflows, threat rules, etc.)
User Config	`/internal/v1/registry/usrcfg/:entity`	Per-user configuration (saved searches, preferences, column layouts)
Module Config	`/internal/v1/registry/modcfg/:entity`	Per-module configuration (module-specific settings and state)

The :entity path parameter identifies the configuration type (e.g., collector.aws, workflow, threat.rule, grid.user).

Endpoints

System Config

Method	Path	Description
`POST`	`/internal/v1/registry/config/:entity`	Create or update a config entry
`GET`	`/internal/v1/registry/config/:entity`	List all config entries for an entity type
`GET`	`/internal/v1/registry/config/:entity/:id`	Get a specific config entry
`DELETE`	`/internal/v1/registry/config/:entity/:id`	Soft-delete a config entry (tombstone)
`DELETE`	`/internal/v1/registry/config/:entity/:id/erase`	Hard-delete a config entry (permanent)

User Config

Method	Path	Description
`POST`	`/internal/v1/registry/usrcfg/:entity`	Create or update a user config entry
`GET`	`/internal/v1/registry/usrcfg/:entity`	List user config entries
`GET`	`/internal/v1/registry/usrcfg/:entity/:id`	Get a specific user config entry
`DELETE`	`/internal/v1/registry/usrcfg/:entity/:id`	Soft-delete a user config entry
`DELETE`	`/internal/v1/registry/usrcfg/:entity/:id/erase`	Hard-delete a user config entry

Module Config

Method	Path	Description
`POST`	`/internal/v1/registry/modcfg/:entity`	Create or update a module config entry
`GET`	`/internal/v1/registry/modcfg/:entity`	List module config entries
`GET`	`/internal/v1/registry/modcfg/:entity/:id`	Get a specific module config entry
`DELETE`	`/internal/v1/registry/modcfg/:entity/:id`	Soft-delete a module config entry
`DELETE`	`/internal/v1/registry/modcfg/:entity/:id/erase`	Hard-delete a module config entry

Additional Endpoints

Method	Path	Description
`GET`	`/internal/v1/registry/collectorAttributes/:entity/:eid`	Get extended attributes for a collector
`GET`	`/internal/v1/scheduler/job_status`	List all scheduler job statuses
`GET`	`/internal/v1/scheduler/job_status/:jid`	Get a specific job status

Config CRUD Operations

All three scopes (config, usrcfg, modcfg) share the same request/response structure. The examples below use the system config scope (/config/); substitute /usrcfg/ or /modcfg/ for other scopes.

POST — Create or Update

Create or update a configuration entry. The request body wraps the actual configuration in a versioned message envelope.

Request:

http

POST /internal/v1/registry/config/:entity
Content-Type: application/json
Authorization: Bearer <token>

json

{
  "message": {
    "id": "collector-uuid",
    "name": "Corporate Active Directory",
    "host": "dc01.corp.local",
    "port": 636,
    "useSsl": true
  },
  "version": null,
  "tombstoned": false
}

Request fields:

Field	Type	Description
`message`	object	The configuration payload (protobuf-derived, varies by entity type)
`version`	bytes/null	Version vector for optimistic concurrency (null for new entries)
`tombstoned`	bool	Automatically set to false on create/update

Response (200): Returns the stored message with an updated version vector.

json

{
  "message": {
    "id": "collector-uuid",
    "name": "Corporate Active Directory"
  },
  "version": "dmVyc2lvbi12ZWN0b3I=",
  "tombstoned": false
}

Note: Sensitive fields (passwords, secrets) are sanitized in responses via the config.Sanitizer interface.

GET — List

List all configuration entries for an entity type.

Request:

http

GET /internal/v1/registry/config/:entity
Authorization: Bearer <token>

Query parameters:

Parameter	Type	Description
`tombstoned`	string	Set to `1` to include soft-deleted entries

Response (200): Array of message envelopes, sorted alphabetically by name.

json

[
  {
    "message": { "id": "uuid-1", "name": "Alpha Collector" },
    "version": "...",
    "tombstoned": false
  },
  {
    "message": { "id": "uuid-2", "name": "Beta Collector" },
    "version": "...",
    "tombstoned": false
  }
]

GET — Get by ID

Retrieve a specific configuration entry.

Request:

http

GET /internal/v1/registry/config/:entity/:id
Authorization: Bearer <token>

Response (200): Single message envelope.

DELETE — Soft Delete

Soft-delete (tombstone) a configuration entry. The entry remains in storage but is excluded from list results unless ?tombstoned=1 is specified.

Request:

http

DELETE /internal/v1/registry/config/:entity/:id
Authorization: Bearer <token>

Response (200): Empty response on success.

Safeguard: Users cannot delete their own grid.user entry.

DELETE — Hard Delete (Erase)

Permanently remove a configuration entry. This operation is irreversible.

Request:

http

DELETE /internal/v1/registry/config/:entity/:id/erase
Content-Type: application/json
Authorization: Bearer <token>

The request body contains the full configuration message to be erased.

Response (200): Empty response on success.

Warning: Erased configurations cannot be recovered. For generic collectors, the system also runs CleanupGenericCollector() to remove associated data.

GET /internal/v1/registry/collectorAttributes/:entity/:eid

Get extended mapping attributes for a generic collector configuration.

Request:

http

GET /internal/v1/registry/collectorAttributes/:entity/:eid
Authorization: Bearer <token>

Path parameters:

Parameter	Description
`entity`	Entity type (must be `collector.generic*` type)
`eid`	Entity/collector ID

Response (200):

json

["customAttribute1", "customAttribute2", "department", "location"]

Returns an array of extended attribute names from the collector's principal mappings.

GET /internal/v1/scheduler/job_status

List all scheduler job statuses. Jobs represent scheduled tasks like data collection runs, mapping cycles, and threat scoring.

Request:

http

GET /internal/v1/scheduler/job_status
Authorization: Bearer <token>

Response (200):

json

[
  {
    "message": {
      "id": "collection-corporate-ad",
      "owner": "collector-uuid",
      "starttime": 1707700800000,
      "finishtime": 1707701100000,
      "metadata": {
        "type": "collection",
        "platform": "Active Directory"
      },
      "next": 1707787200000,
      "runNow": false,
      "locked": false,
      "logs": ["Started collection", "Processed 4521 accounts", "Completed"]
    }
  }
]

Job Status fields:

Field	Type	Description
`id`	string	Job identifier
`owner`	string	ID of the module/collector that owns this job
`starttime`	int64	Last execution start time (ms)
`finishtime`	int64	Last execution finish time (ms)
`metadata`	map	Key-value metadata (type, platform, etc.)
`next`	int64	Next scheduled execution time (ms)
`runNow`	bool	Whether the job is queued for immediate execution
`locked`	bool	Whether the job is currently locked by a running process
`logs`	string[]	Log messages from the last execution

GET /internal/v1/scheduler/job_status/:jid

Get the status of a specific scheduler job.

Request:

http

GET /internal/v1/scheduler/job_status/:jid
Authorization: Bearer <token>

Response (200): Single job status envelope. Returns an empty status object if the job ID is not found.

Common Entity Types

The :entity parameter accepts the following common values:

Entity Type	Description
`collector.ad`	Active Directory collector config
`collector.aws`	AWS collector config
`collector.azure`	Azure AD collector config
`collector.okta`	Okta collector config
`collector.generic*`	Universal connector configs
`credential.*`	Credential store configs
`workflow`	Automation workflow configs
`action.*`	Action provider configs
`threat.rule`	Threat detection rule configs
`grid.user`	Platform user configs
`mapping.rule`	Identity mapping rule configs
`classification.rule`	Account classification rule configs
`savedsearch`	Saved search configs
`notification`	Notification configs

Error Responses

Status	Description
`400`	Invalid request body or unknown entity type
`403`	Authentication failed or attempt to self-delete
`404`	Config entry not found
`409`	Version conflict (optimistic concurrency failure)
`500`	Internal server error

Registry API — Node info, join codes, gateway addresses
Backup & Restore API — Registry and datastore backup operations
Collectors API — Higher-level collector management

Data Sources

Universal Collector Overview

Threat Detection Rules

OpenID Providers

Credentials

How to use the CyberArk Integration

Registry Configuration API ​

Overview ​

Base Path ​

Authentication ​

Configuration Scopes ​

Endpoints ​

System Config ​

User Config ​

Module Config ​

Additional Endpoints ​

Config CRUD Operations ​

POST — Create or Update ​

GET — List ​

GET — Get by ID ​

DELETE — Soft Delete ​

DELETE — Hard Delete (Erase) ​

GET /internal/v1/registry/collectorAttributes/:entity/:eid ​

GET /internal/v1/scheduler/job_status ​

GET /internal/v1/scheduler/job_status/:jid ​

Common Entity Types ​

Error Responses ​

Related Topics ​

Registry Configuration API

Overview

Base Path

Authentication

Configuration Scopes

Endpoints

System Config

User Config

Module Config

Additional Endpoints

Config CRUD Operations

POST — Create or Update

GET — List

GET — Get by ID

DELETE — Soft Delete

DELETE — Hard Delete (Erase)

GET /internal/v1/registry/collectorAttributes/:entity/:eid

GET /internal/v1/scheduler/job_status

GET /internal/v1/scheduler/job_status/:jid

Common Entity Types

Error Responses

Related Topics