REST API Reference

All endpoints are served over HTTPS at /api/v1/. Authenticated endpoints require Authorization: Bearer <token>.

Token types: API tokens (arc_ prefix, persistent), JWT tokens (24h, from login), SSO tokens (from OIDC/SAML/LDAP callback).

Error Format

{
  "error": {
    "code": "not_found",
    "message": "realm not found -- list realms with: arcan realm list",
    "status": 404
  }
}

Pagination

Cursor-based pagination (never offset):

{
  "data": [],
  "next_cursor": "abc123",
  "has_more": true
}

Endpoints

Health

Method	Path	Auth	Description
GET	/api/v1/health	No	Server status, version, component health

Auth

Method	Path	Auth	Description
POST	/api/v1/auth/register	No	Create user account (email, password, name)
POST	/api/v1/auth/login	No	Login with email/password, returns JWT
GET	/api/v1/auth/providers	No	List configured SSO providers

SSO

Method	Path	Auth	Description
GET	/api/v1/auth/oidc/{provider}/login	No	Initiate OIDC login (302 redirect)
GET	/api/v1/auth/oidc/{provider}/callback	No	OIDC callback, returns JWT
GET	/api/v1/auth/saml/{provider}/login	No	Initiate SAML login (302 redirect)
POST	/api/v1/auth/saml/{provider}/acs	No	SAML assertion consumer service
GET	/api/v1/auth/saml/{provider}/metadata	No	SAML SP metadata XML
POST	/api/v1/auth/ldap/{provider}/login	No	LDAP login (username/password)

Tokens

Method	Path	Auth	Description
POST	/api/v1/auth/tokens	Yes	Create API token (name, scopes)
GET	/api/v1/auth/tokens	Yes	List API tokens
DELETE	/api/v1/auth/tokens/{id}	Yes	Revoke a token

Realms

Method	Path	Auth	Description
POST	/api/v1/realms	Yes	Create realm (slug, name)
GET	/api/v1/realms	Yes	List all realms
GET	/api/v1/realms/{slug}	Yes	Get realm details
DELETE	/api/v1/realms/{slug}	Yes (admin)	Soft-delete realm

Secrets

Method	Path	Auth	Description
POST	/api/v1/realms/{slug}/secrets	Yes	Store a secret (key, value, environment)
GET	/api/v1/realms/{slug}/secrets	Yes	List secrets (filter by ?env=)
GET	/api/v1/realms/{slug}/secrets/{key}	Yes	Get a secret (filter by ?env=)
DELETE	/api/v1/realms/{slug}/secrets/{key}	Yes	Delete a secret (filter by ?env=)
POST	/api/v1/encrypt	Yes	Encrypt a plaintext value

Engines

Method	Path	Auth	Description
GET	/api/v1/engines	Yes	List registered engine types
POST	/api/v1/realms/{slug}/engines/{type}/generate	Yes	Generate a secret via engine
POST	/api/v1/realms/{slug}/engines/{type}/validate	Yes	Validate a secret via engine

Policy

Method	Path	Auth	Description
GET	/api/v1/policy/roles	Yes	List roles and capabilities
POST	/api/v1/realms/{slug}/policy/bindings	Yes (admin)	Assign role to user
GET	/api/v1/realms/{slug}/policy/bindings	Yes	List role bindings
DELETE	/api/v1/realms/{slug}/policy/bindings/{userID}	Yes (admin)	Remove role binding

ESO (External Secrets Operator)

Simplified endpoints for the Kubernetes External Secrets Operator webhook provider. Returns only secret values (not full secret objects) so ESO can extract them with jsonPath: $.value.

Default environment is prod (not dev) since ESO typically targets production clusters.

Method	Path	Auth	Description
GET	/api/v1/eso/{realm}/{key}	Yes	Get a single secret value
GET	/api/v1/eso/{realm}	Yes	Bulk fetch all secrets in realm

Query parameters: ?env= (default prod)

Get single secret

GET /api/v1/eso/myapp/DATABASE_URL?env=prod
Authorization: Bearer arc_...

Response (200):

{"value": "postgres://user:pass@db:5432/myapp"}

Error (404):

{"error": "secret not found"}

Bulk fetch all secrets

GET /api/v1/eso/myapp?env=prod
Authorization: Bearer arc_...

Response (200):

{
  "data": {
    "DATABASE_URL": "postgres://user:pass@db:5432/myapp",
    "API_KEY": "sk-abc123",
    "REDIS_URL": "redis://cache:6379"
  }
}

Empty realm returns {"data": {}}.

See External Secrets Operator Integration for Kubernetes setup.

Audit

Method	Path	Auth	Description
GET	/api/v1/audit/events	Yes	Query audit log (filter by realm, type, actor, limit)

Metrics

Method	Path	Auth	Description
GET	/metrics	No	Prometheus metrics