Authentication

Every request carries an API key in the Authorization header, except GET /openapi.json, which is public. A key acts as you: it can do what your role allows in each project you are a member of.

curl https://console.hosthatch.com/api/v1/me/ \
  -H "Authorization: Bearer $HOSTHATCH_API_KEY"

Endpoints

Endpoint	What it does
GET /me/	Get the current user

Create a key

Keys are created on your profile page, under API Keys. The console may ask for your password again first.

Setting	What it does
Name	A label of up to 50 characters, such as deploy script.
Expires	After 30 days, 90 days (the default) or 1 year, or never.
Read-only	The key can read and poll, and nothing else. See Read-only keys.

The key is shown once, when you create it. Copy it into your secret manager or an environment variable then. The profile page lists your keys with their prefix, access, expiry and when each was last used, and is where you revoke them.

Send the key

Send the key as a Bearer token on every request:

Authorization: Bearer <key>

Send it in this header only, never in the URL. A request without it, or with another scheme such as Basic, answers 401 authentication_required with a WWW-Authenticate: Bearer header.

Read-only keys

A read-only key can send GET requests and nothing else: it can list and read everything, and poll actions and orders. Any request that would change something answers 403 read_only_key. A read-only key never sees a reset root password.

Use read-only keys for monitoring, dashboards and agents that only need to look.

Expiry and revocation

• A key past its expiry answers 401 api_key_expired. Create a new one.
• A revoked key answers 401 invalid_api_key, as an unknown or malformed key does.
• Changing or resetting your password revokes every key you have.
• Keys of a deactivated account answer 401 invalid_api_key.

Failed attempts

After 20 failed key checks from one IP address within 10 minutes, every key sent from that address answers 429 rate_limited, even a valid one, until the 10 minutes have passed. Retry-After says how many seconds are left. Fix the key before trying again rather than retrying in a loop.

Keep keys safe

• Keep keys out of code and repositories. Read them from an environment variable or a secret manager.
• Give each script, server and agent its own key, so that you can revoke one without touching the others.
• Use a read-only key wherever you only need to read.
• Choose an expiry. To rotate a key, create the new one, switch to it, then revoke the old one.
• A key carries your access to every project you belong to. Treat it like your password.

Errors

Status	Code	When
401	authentication_required	No key, or a scheme other than Bearer.
401	invalid_api_key	The key is unknown, malformed or revoked, or the account is deactivated.
401	api_key_expired	The key is past its expiry.
403	read_only_key	A read-only key asked for a change.
429	rate_limited	Too many failed key checks from your address, or the key's rate limit.

The current user

Get the current user

GET /me/

Any member · Read-only keys: yes · Returns 200 Me

Who the key belongs to, and the projects it can reach. Use it to check a key and to find your projects' slugs.

curl https://console.hosthatch.com/api/v1/me/ \
  -H "Authorization: Bearer $HOSTHATCH_API_KEY"

{
  "id": 1,
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "billing_account": {"exists": true, "credit_balance": "40.00", "currency": "USD"},
  "projects": [{"slug": "acme", "name": "Acme", "role": "owner"}]
}

Field	Type	Description
id	integer	Your user id.
email	string	Your email address.
first_name, last_name	string	Your name. Either can be empty.
projects	array	The projects you are a member of, by name: each has its slug, which addresses it in every other path, and its name.
projects[].role	string	Your role in the project: owner, admin or member.
billing_account	object	Your own billing account: {"exists": false} when you have none. Otherwise exists is true, credit_balance is your account credit as a decimal string, or null when it can't be read just now, and currency is its currency. Orders in the projects you own are paid from this credit: see Orders and payment.

A user without a project gets an empty projects list.