Skip to Content
homemade
Dashboard

Authentication and errors

Send an API key on every request, and read errors by status and code.

API keys

The API uses API keys. Create one in the dashboard under Account → API keys, or with the CLI:

homemade api-key create --name ci

A key is shown once, so store it right away. It acts as you: it reaches every team you belong to, with your role in each.

Send it as a bearer token on every request. A missing or wrong key answers 401.

curl https://api.homemade.dev/api/me \
  -H "Authorization: Bearer $HOMEMADE_API_KEY"

GET /api/me answers who the key belongs to and its teams. A team's id is the orgId other calls take. Keep keys out of source control, and revoke a leaked one from the same dashboard page.

Errors

A failed request answers a 4xx or 5xx status and a JSON body with an error message a person can read. Where a program should branch on the reason, the body also has a code.

409 Conflict
{
  "error": "This VM is not running right now."
}
StatusMeaning
400The request body or query does not match the schema. The answer lists each problem.
401No API key, or the key is revoked or expired.
402Your plan does not allow it. The answer says why.
403The key's owner may not do this, for example in a team where they are not an admin.
404Nothing with that id in the teams the key can reach.
409The VM is not in a state that allows it, such as running a command in a VM that is asleep.
429Too many changes in a minute, or a plan limit such as VMs at once was reached.

On this page