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