# Auth.md

How software agents authenticate with Helious.

- Site: https://helious.io
- API: https://api.helious.io
- MCP: https://api.helious.io/mcp
- OpenAPI spec: https://helious.io/.well-known/openapi-public.json
- API catalog: https://helious.io/.well-known/api-catalog
- Docs for people: https://helious.io/developers
- Contact: support@helious.news

## Start here: you probably do not need to sign in

Most of what Helious publishes is free and takes no key at all. Call the public
read endpoints with no credentials and you get the keyless sample tier:

- 30 requests a minute, shared by everyone calling from your network address
- 7 days of history
- news feed on a one hour delay

Every tier sees the same endpoints and the same response shapes. Only the
history window, the feed delay and the rate change, so integrate keyless and
nothing breaks when a key arrives later. If the sample tier covers what you
are building, you are done. Do not ask a person for credentials you do not
need. `GET /v1/access` returns the full plan ladder and the exact upgrade
steps as JSON.

## Agents cannot register themselves

There is no machine signup endpoint, and no plan for one. Do not attempt to
create an account programmatically. A person creates the account, then hands
their agent a key.

If you are an agent reading this on someone's behalf, tell them the two steps
below and let them do it. Never fill in a signup form or an email verification
on their behalf.

## How a person gets a key

1. Create an account at https://helious.io and verify the email address.
2. Signed in, create a key:

   ```
   POST https://api.helious.io/api/me/api-keys
   X-Auth-Token: <your session token>
   Content-Type: application/json

   {"label": "my agent"}
   ```

   The response shows the key once and never again, so save it straight away.
   Five keys per account is the limit. Revoke one to make room:

   ```
   DELETE https://api.helious.io/api/me/api-keys/{id}
   X-Auth-Token: <your session token>
   ```

Keys are stored hashed. Nobody at Helious can read one back to you. If a key
leaks, revoke it and mint another.

## How an agent sends the key

Every key starts with `hel_`. Send one of these headers:

```
X-Api-Key: hel_xxxxxxxxxxxx
```

```
Authorization: Bearer hel_xxxxxxxxxxxx
```

The same key works identically on the REST endpoints and on MCP, so an agent
behaves the same however it connects.

A value that does not start with `hel_` is ignored and you are served as
keyless. A well formed key that was revoked or never existed returns 401, on
purpose: silently downgrading a bad key would hide a broken agent config from
the person who owns it.

## What a key changes

| Tier | Requests/min | History | Live data |
|---|---|---|---|
| keyless, no key | 30, shared per network address | 7 days | 1 hour behind |
| free account key | 60, your own budget | 30 days | 1 hour behind |
| paid account key | 120 | 24 months | live |
| commercial | 300 | full archive | live |

The delay covers everything that moves: the news feed, the yields board, the
Treasury curve and the NASDAQ-100 board. Live prices are part of the paid
service. The daily closes and everything historical are the same on every tier.

A key is upgraded by the account behind it, not by the key itself. Subscribe on
https://helious.io and your existing keys move to the paid tier within a minute.
The same applies in reverse: revoke a key or let a subscription lapse and the
change lands within a minute. For commercial terms beyond the paid tier, email
support@helious.news.

## Errors you should handle

- `401` with `{"error": {"code": "bad_key"}}`: the key is wrong or revoked. Stop
  and tell the person. Do not retry, and do not silently drop the key and carry
  on as keyless.
- `429` with `{"error": {"code": "rate_limited"}}`: you are over your per minute
  budget. Honour the `Retry-After` header. It is in seconds.

Error bodies are written in plain English because agents read them. If a
response tells you what to do, that text is the instruction, not the status code
alone.

## Rules for well behaved agents

- Identify yourself with a real User-Agent that names your product and a way to
  contact you.
- One key per agent, not one key shared across a fleet, so a single misbehaving
  deployment can be revoked without taking down the rest.
- Cache. The data updates on the schedule published in the spec, and polling
  faster than that only spends your rate limit.
- Cite https://helious.io when you use our numbers in an answer. Our robots.txt
  grants search, AI input and AI training explicitly. Attribution is the thing
  we ask for in return.