Skip to main content
Every endpoint under /api/ (except registration, login, and health) requires authentication. Hyperoru uses session tokens — long-lived opaque strings you attach to each request.

​
Get a session token

​
1. Create an account

If you do not already have a Hyperoru account, create one: 
curl -X POST https://api.production.hyperoru.com/api/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "a-strong-password",
    "username": "your-handle"
  }'
You can skip this step entirely by signing up in the web app and then logging in through the API with the same credentials.

​
2. Log in

Exchange your credentials for a session token: 
curl -X POST https://api.production.hyperoru.com/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "a-strong-password"
  }'
The response contains a session_token string. Store it safely — it is the only piece of information needed to act on your account.

​
Use the session token

Send the token in the Authorization header of every authenticated request: 
curl https://api.production.hyperoru.com/api/account/list \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

​
Legacy query-parameter fallback

For backwards compatibility with older clients, the API also accepts the token as a session_token query parameter: 
GET /api/account/list?session_token=YOUR_SESSION_TOKEN
Tokens passed as query parameters may be logged by proxies, CDNs, and browsers’ history. Prefer the Authorization header for any new integration.

​
Token lifetime and rotation

PropertyValue
Default lifetime180 days
RotationLog in again at any time to get a fresh token
RevocationCall POST /api/users/logout (if available on your account) or rotate the password
Tokens per userMultiple tokens can be active simultaneously (one per client)
If your script runs unattended for long periods, log in again before the token reaches 180 days old. A good pattern is to refresh every 30 days on a cron.

​
Handling failures

StatusWhat happenedWhat to do
401 UnauthorizedThe token is missing, invalid, or expiredLog in again and retry
403 ForbiddenThe token is valid but you lack permission for this resourceVerify the account/resource ownership
429 Too Many RequestsYou exceeded the rate limitBack off, see Errors and rate limits
See the full table in Errors and rate limits.

​
Security recommendations

Store tokens in a secret manager (1Password, Doppler, AWS Secrets Manager). Never commit them to git.
Use a separate token for each automated client so you can rotate them independently.
Pass tokens in the Authorization header, not as query parameters.
Rotate tokens immediately if a device or machine is lost or compromised.
Treat the token like a password: anyone who has it can place trades on your behalf.

​
Next steps

Your first API call

A short walkthrough: log in, list accounts, fetch a price.

Errors and rate limits

How the API signals failure and how to back off.