Registries

Registries are the source of every image HarborGuard scans. Each registry is bound to one organization, is encrypted at rest using envelope encryption, and may run in either cloud mode (HarborGuard pulls images directly) or sensor mode (a HarborGuard sensor inside your network performs the pull and reports back).

Base path: /api/registries

Method	Path	Min role
GET	`/api/registries`	viewer (any)
POST	`/api/registries`	`admin`
GET	`/api/registries/{registryId}`	viewer (any)
PUT	`/api/registries/{registryId}`	`admin`
DELETE	`/api/registries/{registryId}`	`admin`
POST	`/api/registries/test-connection`	`developer`
POST	`/api/registries/{registryId}/sync`	`admin`
GET	`/api/registries/{registryId}/sensor-status`	viewer (any)
POST	`/api/registries/schedule-scans`	`admin`

Supported providers

The provider enum is fixed:

DOCKER_HUB | GHCR | AWS_ECR | AZURE_ACR | GOOGLE_GAR
GITLAB     | HARBOR | JFROG  | QUAY      | NEXUS
DOCKER_REGISTRY (any v2-compatible) | CUSTOM

When scanMethod = sensor on POST /registries, the response includes sensorApiKey (a one-time hg_ak_* value) used by the sensor to authenticate uploads. Credentials are never returned by GET — they are encrypted with a per-registry data encryption key (DEK), which is itself wrapped by the org's key encryption key (KEK).

GET

/registries

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

curl -X GET "https://harborguard.co/api/registries" \
  -H "X-API-Key: <token>"

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "provider": "DOCKER_HUB",
      "url": "string",
      "scanMethod": "cloud",
      "scanning": {
        "schedule": "manual",
        "scanners": [
          "trivy"
        ],
        "tagInclude": "string",
        "tagExclude": "string"
      },
      "imageCount": 0,
      "health": {
        "status": "healthy",
        "lastSyncAt": "2019-08-24T14:15:22Z"
      },
      "sensorApiKey": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}

POST

/registries

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Request Body

application/jsonRequired

`name`
Required
string

`provider`
Required
string

Value in:

"DOCKER_HUB" | "GHCR" | "AWS_ECR" | "AZURE_ACR" | "GOOGLE_GAR" | "GITLAB" | "HARBOR" | "JFROG" | "QUAY" | "NEXUS" | "DOCKER_REGISTRY" | "CUSTOM"

`url`string

Required for DOCKER_REGISTRY, HARBOR, JFROG, NEXUS, GITLAB, CUSTOM.

`credentials`UsernamePassword | UsernamePat | AwsEcr | GoogleGar | AzureAcr | HarborRobot | JfrogIdentityToken

Provider-specific credential payload. Exact required fields vary by provider.

`scanMethod`string

Default: "cloud"Value in: "cloud" | "sensor"

`scanners`array<string>

Default: ["trivy","grype","syft"]

`schedule`string

Default: "daily"Value in: "manual" | "on_push" | "daily" | "weekly"

`includeTags`string

`excludeTags`string

`insecure`boolean

Default: false

curl -X POST "https://harborguard.co/api/registries" \
  -H "X-API-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme GHCR",
    "provider": "GHCR",
    "url": "https://ghcr.io",
    "credentials": {
      "username": "deploy-bot",
      "pat": "ghp_xxx"
    },
    "scanMethod": "cloud",
    "schedule": "daily",
    "includeTags": "v*"
  }'

Created

GET

/registries/{registryId}

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Path Parameters

`registryId`
Required
string

curl -X GET "https://harborguard.co/api/registries/string" \
  -H "X-API-Key: <token>"

{
  "data": {
    "id": "string",
    "name": "string",
    "provider": "DOCKER_HUB",
    "url": "string",
    "scanMethod": "cloud",
    "scanning": {
      "schedule": "manual",
      "scanners": [
        "trivy"
      ],
      "tagInclude": "string",
      "tagExclude": "string"
    },
    "imageCount": 0,
    "health": {
      "status": "healthy",
      "lastSyncAt": "2019-08-24T14:15:22Z"
    },
    "sensorApiKey": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

PUT

/registries/{registryId}

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Request Body

application/jsonRequired

`name`string

`scanning`object

Path Parameters

`registryId`
Required
string

curl -X PUT "https://harborguard.co/api/registries/string" \
  -H "X-API-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scanning": {
      "schedule": "weekly",
      "tagInclude": "release-*"
    }
  }'

DELETE

/registries/{registryId}

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Path Parameters

`registryId`
Required
string

curl -X DELETE "https://harborguard.co/api/registries/string" \
  -H "X-API-Key: <token>"

POST

/registries/test-connection

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Request Body

application/jsonRequired

`provider`
Required
string

Value in:

"DOCKER_HUB" | "GHCR" | "AWS_ECR" | "AZURE_ACR" | "GOOGLE_GAR" | "GITLAB" | "HARBOR" | "JFROG" | "QUAY" | "NEXUS" | "DOCKER_REGISTRY" | "CUSTOM"

`url`string

`credentials`UsernamePassword | UsernamePat | AwsEcr | GoogleGar | AzureAcr | HarborRobot | JfrogIdentityToken

Provider-specific credential payload. Exact required fields vary by provider.

`insecure`boolean

Default: false

curl -X POST "https://harborguard.co/api/registries/test-connection" \
  -H "X-API-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "DOCKER_HUB",
    "url": "string",
    "credentials": {
      "username": "string",
      "password": "string"
    },
    "insecure": false
  }'

POST

/registries/{registryId}/sync

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Path Parameters

`registryId`
Required
string

curl -X POST "https://harborguard.co/api/registries/string/sync" \
  -H "X-API-Key: <token>"

Accepted

GET

/registries/{registryId}/sensor-status

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

Path Parameters

`registryId`
Required
string

curl -X GET "https://harborguard.co/api/registries/string/sensor-status" \
  -H "X-API-Key: <token>"

POST

/registries/schedule-scans

Authorization

`X-API-Key`<token>

Organization API key (hg_ak_*). Created from Settings → API Keys.

In: header

`Authorization`
Required
Bearer <token>

Authorization: Bearer hg_ak_... for organization API keys, or Authorization: Bearer hg_pat_... for Personal Access Tokens that impersonate a specific user.

In: header

`next-auth.session-token`<token>

NextAuth session cookie. Web only — set automatically at sign-in. Not usable for server-to-server.

In: cookie

curl -X POST "https://harborguard.co/api/registries/schedule-scans" \
  -H "X-API-Key: <token>"

Accepted

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

Response

TypeScript

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

nameRequiredstring

providerRequiredstring

urlstring

credentialsUsernamePassword | UsernamePat | AwsEcr | GoogleGar | AzureAcr | HarborRobot | JfrogIdentityToken

UsernamePassword

UsernamePat

AwsEcr

GoogleGar

AzureAcr

HarborRobot

JfrogIdentityToken

scanMethodstring

scannersarray<string>

schedulestring

includeTagsstring

excludeTagsstring

insecureboolean

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

registryIdRequiredstring

Response

TypeScript

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

namestring

scanningobject

Attributes

registryIdRequiredstring

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

registryIdRequiredstring

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

providerRequiredstring

urlstring

credentialsUsernamePassword | UsernamePat | AwsEcr | GoogleGar | AzureAcr | HarborRobot | JfrogIdentityToken

UsernamePassword

UsernamePat

AwsEcr

GoogleGar

AzureAcr

HarborRobot

JfrogIdentityToken

insecureboolean

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

registryIdRequiredstring

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

registryIdRequiredstring

X-API-Key<token>

AuthorizationRequiredBearer <token>

next-auth.session-token<token>

On this page

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`name`
Required
string

`provider`
Required
string

`url`string

`credentials`UsernamePassword | UsernamePat | AwsEcr | GoogleGar | AzureAcr | HarborRobot | JfrogIdentityToken

`scanMethod`string

`scanners`array<string>

`schedule`string

`includeTags`string

`excludeTags`string

`insecure`boolean

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`registryId`
Required
string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`name`string

`scanning`object

`registryId`
Required
string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`registryId`
Required
string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`provider`
Required
string

`url`string

`credentials`UsernamePassword | UsernamePat | AwsEcr | GoogleGar | AzureAcr | HarborRobot | JfrogIdentityToken

`insecure`boolean

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`registryId`
Required
string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>

`registryId`
Required
string

`X-API-Key`<token>

`Authorization`
Required
Bearer <token>

`next-auth.session-token`<token>