Authentication

How to authenticate with the API.


Get an API Key

  1. Go to settings → workspace → api keys
  2. Click Create API Key. Workspace owners and admins choose whether it acts as them (personal) or as the workspace (workspace, for CI and servers). See API keys.
  3. Copy the key (starts with inf_)

Keys can be scoped to least privilege — for example apps:execute without secrets:write. See API Keys API for the scope catalog (GET /scopes), preset bundles, and programmatic create/list/revoke.


Keep it Secret

  • Don't commit to git
  • Don't share publicly
  • Use environment variables
bash
1export INFERENCE_API_KEY="inf_your_key"

Browser apps? Never expose API keys in client-side code. Use a Server Proxy to keep credentials safe.


Using the Key

With SDKs

1from inferencesh import inference23# Direct4client = inference(api_key="inf_your_key")56# From the INFERENCE_API_KEY environment variable7client = inference()

The Python SDK reads INFERENCE_API_KEY when api_key is omitted (inferencesh ≥ v0.22.0); an explicit api_key wins. With neither, creating the client raises ValueError. The JavaScript and Swift clients take the key only as an argument.

With the CLI

bash
1belt login                                 # browser approval, stores a session2export INFERENCE_API_KEY="inf_your_key"    # or: an API key for CI and headless machines3belt app run infsh/echo --input '{"message": "Hello!"}'

The CLI reads the same INFERENCE_API_KEY as the SDKs and curl. INFSH_API_KEY still works but is deprecated: belt prints a warning, and INFERENCE_API_KEY wins when both are set. See CLI setup: login.

With REST API

bash
1curl https://api.inference.sh/apps/run \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{"app": "infsh/echo", "input": {"message": "Hello!"}}'

See REST overview — response format for response and error formats.


Workspace context

Most API resources are scoped to a workspace (a team in the API). Which workspace a request uses depends on how the API key was created:

Key sourceWorkspace context
settings → workspace → api keys (manually created)Fixed to the workspace selected when the key was created. A personal key acts as you there and stops working if you leave; a workspace key acts as the workspace and is the one to use for CI and automation.
Device authorization (belt login, CLI)Acts as you. Can switch workspaces with X-Team-ID or belt auth switch.
belt auth token (temporary key for scripts)Fixed to the workspace active when it was minted, like a manually created key. Expires in 15 minutes by default, 24 hours at most. See temporary keys.

To act as another workspace you belong to with a device-auth key, send its ID:

bash
1curl https://api.inference.sh/apps/my \2  -H "Authorization: Bearer inf_your_key" \3  -H "X-Team-ID: team_abc123"

You must be a member of that workspace. If the header names a workspace you cannot access, it is ignored and the key's current workspace is used.

Manually created keys and temporary keys ignore X-Team-ID. A leaked CI or automation key cannot be pointed at your other workspaces via a header. Create separate keys per workspace, or use device authorization for interactive tooling that needs to switch workspaces.

In the CLI, use belt auth switch instead of setting the header manually.


Sign-in APIs

API keys are for programmatic access. To sign users into the web app (browser session) or CLI, use the dedicated auth endpoints:

FlowUse caseGuide
Magic link + login codeEmail passwordless sign-in for the web appMagic link API
Two-step verificationSettings, passkeys, recovery codes, login/re-auth verifyTwo-step verification API
Device authorizationCLI, IDE, and headless login (belt login)Device authorization API
Standard OAuth device grantOff-the-shelf OAuth 2.0 client librariesDevice authorization — RFC endpoints

Magic link sign-in returns a session cookie. Device authorization returns a session token (recommended; token_kind: "session") or a legacy API key on the first successful poll after browser approval (one-shot delivery). Session tokens are sent as Authorization: Bearer … and behave like web sessions, including switching workspaces with X-Team-ID and revocation from settings → personal → sessions or via POST /oauth/revoke (RFC 7009).

Sign-in sessions (browser cookie or CLI bearer session token) share a sliding idle window: when less than half of the current lifetime remains, each authenticated API request extends expiry to seven days from now without rotating the token. Sessions approved with a custom expires_in shorter than seven days keep a fixed expiry and are not extended. See Device authorization — Sliding lifetime.

New signups cannot use disposable or temporary email domains. The rule applies to magic link, OAuth, and SAML sign-up. See REST overview: Signup email restrictions.


Two-step verification

Accounts can require a second factor at sign-in and for sensitive browser actions. In the web app, manage enrollment under Settings → Security: turn two-step verification on, add authenticator apps or passkeys, and save recovery codes.

WhoSign-in
Platform staffAlways asked for a second factor. Until an authenticator app or passkey is enrolled, only an emailed code is offered (no platform admin powers until an authenticator is proved).
MembersAsked only when two-step verification is turned on in settings (after at least one authenticator app or passkey is enrolled).

Passwordless browser sign-ins that need a second factor redirect to /auth/verify with a challenge_token. JSON clients receive otp_required: true, otp_methods (for example ["email"], ["totp","recovery"], or ["passkey","totp","recovery"]), and challenge_token on the auth response, then call the verify endpoints documented in Two-step verification API.

Enrollment and settings (GET /auth/second-factor, TOTP enroll/confirm, passkey registration, recovery codes) are covered in the Two-step verification API reference.


Install SDKs

1pip install inferencesh23# With async support4pip install inferencesh[async]

Next

→ SDK Overview — Running apps, streaming, files → Server Proxy — Protect API keys in browser apps

we use cookies

we use cookies to ensure you get the best experience on our website. for more information on how we use cookies, please see our cookie policy.

by clicking "accept", you agree to our use of cookies.
learn more.