Authentication & Activation

Hydracept has two kinds of credentials: who you are (Hydracept identity) and who pays for inference (provider keys). Keep them separate.

Humans can activate in the browser or through CLI device authorization.

Studio (recommended for creators)

Visit https://app.hydracept.com/login
Sign in with GitHub or Google
Complete onboarding (project name and use case)
Generate in Studio; connect BYOK under Connections; upgrade under Billing

Browser API activation

Visit https://hydracept.com/start
Sign in with GitHub or Google
Save the one-time API key shown on the completion page


pip install -U hydracept
python -m hydracept login

The CLI calls POST /v1/auth/device/start and prints a user code
Your browser opens https://api.hydracept.com/device
Sign in (GitHub/Google), enter the code, approve
The CLI polls POST /v1/auth/device/token and writes .hydracept/secrets.json
Run python -m hydracept configure for project config (or quickstart for agents)

After browser activation:


python -m hydracept quickstart --token "$HYDRACEPT_API_KEY" --json --smoke

Legacy path:


python -m hydracept login --token "$HYDRACEPT_API_KEY"
python -m hydracept init --apply --yes
python -m hydracept doctor
python -m hydracept smoke

If the hydracept console script is not on your PATH (common after pip install --user on Windows), use python -m hydracept ….

Browser sessions are for Studio and device approval. Game runtimes and CI should use API keys, not browser cookies.

Project and environment provisioning

Onboarding creates:

an organization
a project (projectId, often cpr_…)
an environment (for example development)

Every capability job needs that context:


{
  "context": {
    "productId": "my-product",
    "projectId": "cpr_...",
    "environment": "development"
  }
}

Machine / service credential

Machine callers use a Hydracept API key as a bearer token:


Authorization: Bearer <HYDRACEPT_API_KEY>

Recommended environment variables:

Variable	Purpose
`HYDRACEPT_API_URL`	API base (`https://api.hydracept.com`)
`HYDRACEPT_API_KEY`	Your API key
`HYDRACEPT_PROJECT`	Project id
`HYDRACEPT_ENVIRONMENT`	Environment name

Do not ship Hydracept API keys in game clients. For player-facing apps, call Hydracept from your server.

CLI helpers:


python -m hydracept login --token <key>
python -m hydracept init --apply --yes
python -m hydracept doctor
python -m hydracept smoke

Provider / BYOK connection

Provider credentials (OpenAI, ElevenLabs, and others) are separate from your Hydracept login.

Hydracept stores them encrypted, validates them, and binds them to projects/environments so execution can resolve BYOK keys at runtime. See Connections / BYOK.

Concern	Owned by
Who is calling Hydracept	Hydracept human session or API key
Which model account pays for inference	Customer provider credential (BYOK)

Without BYOK, run python -m hydracept smoke once using the Free smoke budget, then connect a provider for production jobs. The 5-minute game asset tutorial walks through this end to end.

Verify

python -m hydracept doctor (or hydracept doctor) runs integration checks and prints Next actions on failure:

API health (GET /healthz)
Authenticated diagnostics (GET /v1/diagnostics/session, GET /v1/session/context)
Local .hydracept/config.json alignment with server project/environment
Provider readiness + smoke budget remaining (GET /v1/diagnostics/providers)
Public capability list includes the smoke capability (default image.generate.v1)

Exit code is non-zero when a fatal check fails. Use --json for CI output.


GET /v1/diagnostics/session
Authorization: Bearer <HYDRACEPT_API_KEY>

For agent discovery without hardcoding internals: GET /v1/agent-context.