Request an API key for a site YOU ARE RUNNING ON (challenge-response).
⚠ ONLY USE THIS IF YOU ARE EXECUTING INSIDE THAT SITE'S OWN CONTAINER. If
you bought or ordered the site from somewhere else, this is the wrong tool:
it returns "pending" and the pending never resolves, because the proof it
asks for is a file you cannot reach. Use `get_checkout_status(checkout_id)`
on the checkout that paid for the site — that hands over the site-scoped key
over plain HTTP with no container access. The refusal and the pending
response both name it under `alternative` when one is available.
Two-step verification flow:
1. A claim token is written into that site's container, at the per-site path
the response gives you in `claim_path` (mode 600, owner admin — readable
only from on the container). Do not hardcode the path.
2. Read that file and call claim_api_key(token) within 1 hour
Refused for sites on SHARED containers. One container there serves up to 40
customers behind one agent, so reading a file proves you are on the machine,
not which customer you are — the token would authenticate the wrong thing.
No authentication needed — the proof is reading the file from the container.
Args:
site_slug: The site identifier (your BorealHost site slug)
Returns:
{"status": "pending", "site_slug": "my-site", "expires_in_seconds": 3600,
"claim_path": "/home/admin/.borealhost/.claim_token_my-site",
"requires_container_access": true,
"instructions": "Read the claim token and call claim_api_key()...",
"alternative": {"checkout_id": "...", "command": "bh checkout status ..."}}
Errors:
VALIDATION_ERROR: Unknown site slug, no active subscription, shared
container, or a key already exists (rotate it, never revoke it to
reach this route). Carries `alternative` when another route works.
RATE_LIMITED: Too many pending claim tokens
