Secrets API¶

The Secrets API manages secrets (API keys, tokens, credentials) used by agents to authenticate with external systems. Secrets are stored either in the customer's HashiCorp Vault instance (if configured) or encrypted in the ARX database. Secret values are never returned in API responses, never written to logs, and never stored in the audit trail.

All endpoints are scoped to the authenticated user's organization via Row-Level Security.

List Secrets¶

Retrieves secret metadata for the organization. Secret values are never included in the response.

Method: GET
Path: /v1/secrets
Required Role: Any authenticated user

Query Parameters¶

Parameter	Type	Required	Description
`agent_id`	`UUID`	No	Filter secrets by agent.

Response¶

{
  "secrets": [
    {
      "id": "sec-uuid",
      "org_id": "org-uuid",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "CROWDSTRIKE_API_KEY",
      "connector_type": "crowdstrike",
      "description": "CrowdStrike Falcon API key for detection retrieval",
      "storage": "vault",
      "last_rotated_at": "2026-04-01T00:00:00Z",
      "created_at": "2026-03-15T10:00:00Z"
    }
  ],
  "total": 1
}

The storage field indicates where the secret is stored: vault (customer's HashiCorp Vault) or db (encrypted in the ARX database).

Example¶

curl -X GET "https://api.arxsec.io/v1/secrets?agent_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}"

Create Secret¶

Creates a new secret. If the organization has a Vault integration configured, the secret is stored in the customer's Vault. Otherwise, it is encrypted and stored in the database.

Method: POST
Path: /v1/secrets
Required Role: admin or deployer

Request Body¶

Field	Type	Required	Description
`agent_id`	`UUID`	Yes	The agent this secret is associated with.
`name`	`string`	Yes	Secret name (1--255 characters). Used as the identifier.
`value`	`string`	Yes	The secret value. Stored encrypted, never returned in responses.
`connector_type`	`string`	No	Connector type this secret is used for.
`description`	`string`	No	Human-readable description of the secret's purpose.

Example¶

curl -X POST "https://api.arxsec.io/v1/secrets" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "CROWDSTRIKE_API_KEY",
    "value": "your-secret-value-here",
    "connector_type": "crowdstrike",
    "description": "CrowdStrike Falcon API key for detection retrieval"
  }'

Response¶

Returns the created secret metadata with HTTP status 201 Created. The value field is never included in the response. The creation is audit-logged with the secret name and storage backend.

Rotate Secret¶

Replaces the value of an existing secret. The previous value is overwritten in the storage backend (Vault or encrypted database).

Method: POST
Path: /v1/secrets/{secret_id}/rotate
Required Role: admin

Path Parameters¶

Parameter	Type	Description
`secret_id`	`UUID`	The secret's unique identifier.

Query Parameters¶

Parameter	Type	Required	Description
`new_value`	`string`	Yes	The new secret value.

Example¶

curl -X POST "https://api.arxsec.io/v1/secrets/sec-uuid/rotate?new_value=new-secret-value-here" \
  -H "Authorization: Bearer {token}"

Response¶

Returns the updated secret metadata with last_rotated_at set to the current timestamp. The rotation is audit-logged with the secret name.

Delete Secret¶

Deletes a secret from both the ARX database and the storage backend (Vault, if applicable).

Method: DELETE
Path: /v1/secrets/{secret_id}
Required Role: admin

Path Parameters¶

Parameter	Type	Description
`secret_id`	`UUID`	The secret's unique identifier.

Example¶

curl -X DELETE "https://api.arxsec.io/v1/secrets/sec-uuid" \
  -H "Authorization: Bearer {token}"

Response¶

Returns HTTP status 204 No Content on success. Returns 404 if the secret is not found. If the secret is stored in Vault, it is deleted from Vault as well. Vault deletion failures are logged but do not prevent the database record from being removed. The deletion is audit-logged with the secret name.