Accounts and Billing
This page covers your Goodeye identity (handles), API keys for programmatic access, and the credit model that gates LLM-powered features such as verifier runs, workflow optimization, and template safety checks.
Handles
A handle is your public identity on the Goodeye platform. It is used as the author namespace when you publish templates (for example, @alice/my-template). Handles are lowercase alphanumeric with hyphens, 3 to 40 characters, start and end with an alphanumeric character, and are unique across all users and teams.
Claiming your handle
After signing up, your account has a provisional (unclaimed) handle. You must claim a handle before you can create a team or publish a template.
goodeye me claim-handle alice
PATCH /v1/me
Content-Type: application/json
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
{"handle": "alice"}
MCP tool: claim_handle
On success the response includes handle and claimed_at. Structured errors:
Renaming your handle
goodeye me rename-handle newname
POST /v1/me/rename-handle
Content-Type: application/json
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
{"handle": "newname"}
MCP tool: rename_handle
Rate limits: you may rename once per rolling 90-day window and at most three times per UTC calendar year. If you rename and then rename back (or reclaim a handle you released), and your old handle is still inside its 90-day reservation window, the reclaim is free and does not count against either limit.
Your old handle enters a 90-day reservation window so that any URLs you published under it continue to resolve via redirect. If your old handle was ever stamped on a published template version it is permanently reserved and cannot be claimed by anyone else.
Additional structured errors for rename:
API keys
API keys let you authenticate programmatically with both the REST API and the MCP endpoint. All keys are prefixed good_live_.
Creating a key
goodeye auth create-key --name "CI pipeline"
goodeye auth create-key --name "MCP client" --copy # also copies to clipboard
POST /v1/api-keys
Content-Type: application/json
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
{"name": "CI pipeline"}
MCP tool: mint_api_key
The response includes id, name, key, and created_at. The key value is the full good_live_... secret and is shown exactly once. Store it immediately in a secrets manager or environment variable. It cannot be retrieved again.
Listing keys
goodeye auth list-keys
goodeye auth list-keys --table
GET /v1/api-keys
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
MCP tool: list_api_keys
List responses include id, name, and created_at only. Secret material is never returned after creation.
Revoking a key
goodeye auth revoke-key key_01ABC...
DELETE /v1/api-keys/{key_id_or_name}
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
MCP tool: revoke_api_key
A revoked key stops working immediately. Revocation cannot be undone. The REST route returns 204 on success and 404 on a second delete or an unknown key.
Using a key
Pass your key in the Authorization header for both REST and MCP requests:
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
Security tips:
- Treat API keys like passwords: store them in environment variables or a secrets manager, never in source code.
- Rotate keys regularly by creating a new one and revoking the old one.
- Revoke a key immediately if it is exposed.
Usage and credits
Goodeye uses a credit system to meter LLM-powered features. Each account has a monthly grant that refills at the start of each billing period.
Checking your usage
goodeye usage
goodeye usage --json
GET /v1/me/usage
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
MCP tool: get_usage
Example output:
Tier: hobby
Available: $3.21
refills to $5.00 on 07/01/2026
The response fields are:
Run goodeye usage to see the actual dollar amounts for your tier. Amounts are not hardcoded in this document because they may change.
Tiers
Anonymous callers (no auth) who reach public REST endpoints that consume credits have their own small monthly grant, tracked per network address. This covers use cases like running a verifier against a published template without signing in.
Billing errors
When your budget is exhausted, LLM-powered operations (verifier runs, workflow optimization, design sessions) return 402. Other operations (saving workflows, listing templates, managing teams) are not credit-gated and continue to work.