# HLOS Documentation: API Reference

> Source: https://hlos.ai/docs/api
> Last updated: 2026-01-10
> Context: HLOS is a financial control plane for AI agents. Agents never receive credentials directly.

# API Reference

REST API endpoints for programmatic access.

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.

## Authentication Endpoints

### POST /v1/auth/token

Exchange OAuth code for access token.

**Parameters:**
- `code` (string, required): OAuth authorization code
- `redirect_uri` (string, required): Redirect URI used in OAuth flow

**Response:**
```json
{ "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }
```

### GET /v1/auth/me

Get current authenticated user info.

**Response:**
```json
{ "id": "user_...", "email": "user@example.com", "name": "John Doe" }
```

## Spaces Endpoints

### GET /v1/spaces

List all spaces accessible to the authenticated user.

**Parameters:**
- `limit` (number, optional): Max results (default: 20, max: 100)
- `offset` (number, optional): Pagination offset

### POST /v1/spaces

Create a new space.

**Parameters:**
- `name` (string, required): Space name (lowercase, hyphens only)
- `description` (string, optional): Optional description

### GET /v1/spaces/:id

Get a specific space by ID.

### DELETE /v1/spaces/:id

Delete a space and all its secrets.

## Secrets Endpoints

### GET /v1/secrets

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

**Parameters:**
- `spaceId` (string, optional): Filter by space
- `provider` (string, optional): Filter by provider type
- `scope` (string, optional): Filter by scope
- `search` (string, optional): Search secret names

### GET /v1/secrets/:name

Get a specific secret value. Requires explicit permission.

### POST /v1/secrets

Create a new secret.

**Parameters:**
- `name` (string, required): Secret name (UPPER_SNAKE_CASE)
- `value` (string, required): Secret value
- `spaceId` (string, optional): Target space
- `provider` (string, optional): Provider type
- `scope` (string, optional): Secret scope

### PUT /v1/secrets/:name

Update an existing secret value.

### DELETE /v1/secrets/:name

Delete a secret.

## Health Endpoints

### GET /v1/health

Check health status of secrets in a space.

**Parameters:**
- `spaceId` (string, optional): Target space
- `severity` (string, optional): Min severity (low/medium/high/critical)

## JavaScript SDK

```bash
npm install @hlos/sdk
```

```javascript
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');
```

## Rate Limits

- **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`