H
HLOS Docs

API Reference

REST API endpoints for programmatic access

View as Markdown

The HLOS API allows you to manage secrets programmatically. All endpoints require authentication via Bearer token or API key.

Base URL

https://api.hlos.ai

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate API keys from your HLOS dashboard under Settings → API Keys.

POST/v1/auth/token

Exchange OAuth code for access token.

Parameters:
codestringrequiredOAuth authorization code
redirect_uristringrequiredRedirect URI used in OAuth flow
Response:{ "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }
GET/v1/auth/me

Get current authenticated user info.

Response:{ "id": "user_...", "email": "user@example.com", "name": "John Doe" }
GET/v1/spaces

List all spaces accessible to the authenticated user.

Parameters:
limitnumberMax results (default: 20, max: 100)
offsetnumberPagination offset
Response:{ "items": [...], "total": 5, "hasMore": false }
POST/v1/spaces

Create a new space.

Parameters:
namestringrequiredSpace name (lowercase, hyphens only)
descriptionstringOptional description
Response:{ "id": "space_...", "name": "my-project", "createdAt": "..." }
GET/v1/spaces/:id

Get a specific space by ID.

Response:{ "id": "space_...", "name": "my-project", "secretCount": 12, ... }
DELETE/v1/spaces/:id

Delete a space and all its secrets.

Response:{ "deleted": true }
GET/v1/secrets

List secrets in a space (metadata only, never values).

Parameters:
spaceIdstringFilter by space (default: active space)
providerstringFilter by provider type
scopestringFilter by scope (development/staging/production)
searchstringSearch secret names
Response:{ "items": [{ "id": "...", "name": "OPENAI_API_KEY", "provider": "openai", ... }], ... }
GET/v1/secrets/:name

Get a specific secret value. Requires explicit permission.

Parameters:
spaceIdstringSpace to look in
Response:{ "name": "OPENAI_API_KEY", "value": "sk-...", "provider": "openai" }
POST/v1/secrets

Create a new secret.

Parameters:
namestringrequiredSecret name (UPPER_SNAKE_CASE)
valuestringrequiredSecret value
spaceIdstringTarget space
providerstringProvider type
scopestringSecret scope
descriptionstringOptional description
Response:{ "id": "secret_...", "name": "API_KEY", "createdAt": "..." }
PUT/v1/secrets/:name

Update an existing secret value.

Parameters:
valuestringrequiredNew secret value
spaceIdstringTarget space
Response:{ "updated": true, "name": "API_KEY" }
DELETE/v1/secrets/:name

Delete a secret.

Parameters:
spaceIdstringTarget space
Response:{ "deleted": true }
GET/v1/health

Check health status of secrets in a space.

Parameters:
spaceIdstringTarget space
severitystringMin severity (low/medium/high/critical)
Response:{ "issues": [{ "secretName": "...", "type": "rotation_overdue", "severity": "high", ... }] }

JavaScript SDK

For a simpler interface, use the official SDK:

npm install @hlos/sdk
import { HlosClient } from '@hlos/sdk';

const hlos = new HlosClient({
  apiKey: process.env.HLOS_API_KEY,
});

// List all spaces
const spaces = await hlos.spaces.list();

// Get secrets from a space
const secrets = await hlos.secrets.list('my-project');

// Get a specific secret value
const apiKey = await hlos.secrets.get('my-project', 'OPENAI_API_KEY');

// Set a secret
await hlos.secrets.set('my-project', 'NEW_KEY', 'secret-value');

Rate Limits

API requests are rate limited per account:

  • • Free tier: 100 requests/minute
  • • Pro tier: 1,000 requests/minute
  • • Enterprise: Custom limits

Rate limit headers are included in all responses: X-RateLimit-Remaining