Authentication

Every API call except a few public ones needs an API key, sent as a bearer token:

Authorization: Bearer gf_...

curl -s "https://api.gpuforge.io/v1/billing" -H "Authorization: Bearer $GF_KEY"

#Signing in

You sign in to the console at console.gpuforge.io with Google or GitHub. GPU Forge never sees your Google or GitHub password. A returning sign-in is matched on the identity provider's own account id, not on your email address, so changing your email changes nothing.

A console sign-in lasts 30 days.

#API keys

An API key lets a script, an agent or the CLI act for your account.

#Create a key

Keys are created by you, signed in on the console: API keys → Create, or Guide → Make a key for my agent. Give each project or agent its own key, so you can revoke one without touching the others.

#Revoke a key

Revoke a key on the console (API keys). Revocation stops every new request made with that key at once. Work already accepted (a running machine, a queued job) is not stopped by revoking the key; stop it separately if needed.

A key can also revoke itself:

curl -s -X POST "https://api.gpuforge.io/v1/cli/logout" -H "Authorization: Bearer $GF_KEY"

{"revoked": true, "key_id": "key_..."}

#Check which account a key belongs to

curl -s "https://api.gpuforge.io/v1/cli/whoami" -H "Authorization: Bearer $GF_KEY"

{"admin": false, "user_id": "usr_...", "key_id": "key_...", "name": "Ada Example", "email": "ada@example.com"}

You need the user_id when you create a capability.

#What a key may and may not do

There are no per-key scopes: every API key has the same rights over its own account. Some actions are reserved for you, signed in on the console, so that an agent holding a key can never do them:

#The CLI login

The gpuforge command-line tool signs in through your browser, like other developer CLIs:

1. gpuforge login starts a login (POST /v1/cli/login, no key needed) and opens a page on the console showing a short code such as ABCD-EF23.
2. You check the code matches, and press Approve while signed in.
3. The CLI polls POST /v1/cli/login/poll. After approval it receives a new API key, once, and saves it to ~/.config/gpuforge/config.json (readable only by you).

A login code expires after 10 minutes. gpuforge logout revokes the key on this computer. See Command-line tool.

#Program keys (on your own machine)

When you add a ready program to your account (POST /v1/catalog/{program_id}/add), you also get a program key (gf_api_key, starting with gfv_). It is different from your API key:

The program key is shown once. You can set a new one on your copy of the program; machines started after the change use it:

curl -s -X PATCH "https://api.gpuforge.io/v1/capabilities/<your copy id>" \
  -H "Authorization: Bearer $GF_KEY" -H "Content-Type: application/json" \
  -d '{"secrets": {"env": {"GF_API_KEY": "<a long random string>"}}}'

You can also make a program key on the console (Guide → New program key).

#Keeping keys safe

• Never put a key in client-side code, a public repository or a URL.
• Use one key per project or agent, and revoke keys you no longer use.
• If you think a key has leaked, revoke it on the console at once and tell support@gpuforge.io.

#Authentication errors

This page as Markdown, for tools and agents: /docs/authentication.md