Skip to main content

​
Authenticate with the EvalGate API

Human CLI requests use the revocable session created by evalgate login. SDK, REST, MCP, A2A, and CI automation use an explicitly created API key. SDK clients also need an organization ID when they create org-scoped resources such as traces and evaluations.

​
Create an account

Production account creation uses an interactive browser redirect with GitHub or Google at evalgate.com/signup. Choose one provider and approve its identity request.
  • EvalGate does not ask for a separate email/password pair.
  • The social sign-in flow does not send a separate EvalGate verification email.
  • No payment card is required for Developer’s 10,000-result monthly allowance.
  • Paid tiers and Developer overage continue at $1 per 1,000 additional results without a default usage or dollar cap.
  • Social sign-in requires JavaScript and an interactive browser for the person proving identity. An agent can initiate a credential handoff over HTTP, but a signed-in organization admin must still approve the organization and scopes.
After sign-in, create or join an organization. Then create a scoped API key under Developer → API Keys. Connect a repository in Setup only when the workflow needs repository intelligence or CI, and add a separate model-provider key only for model-backed execution.

​
EvalGate keys and provider keys are different

EvalGate uses a bring your own provider key (BYOK) model and does not bundle model inference credits. Your provider bills model usage directly. A provider key is never a substitute for the EvalGate bearer token, and you should not put it in EVALGATE_API_KEY. See Model providers and BYOK.

​
Create an API key

API keys are created from the Developer Dashboard. You need an EvalGate account before you begin.
1

Open the Developer Dashboard

Sign in to your EvalGate account and navigate to the Developer Dashboard. Scroll down to the API Keys section.
2

Create the key

Click Create API Key. Enter a descriptive name such as Development Key or CI Pipeline, select the scopes you need, then click Create Key.
3

Copy the key and organization ID

Your API key is displayed only once. Copy it before closing the dialog.
If you close the dialog without copying the key, you cannot retrieve it. Create a new key instead.
The dialog also shows your Organization ID. Save that UUID value alongside your key.

​
Agent and CLI setup

The TypeScript and Python CLIs handle their session directly. Login opens the browser-approved device flow, and link establishes the durable organization, GitHub repository, and repository-relative root association without asking the user to copy a key:
The CLI session is stored in the operating-system user configuration directory, outside the repository. Use evalgate logout to revoke the remote session and then remove its local handle. Agents should start with the non-mutating status contract:
.evalgate/project.json is a non-secret version 2 link record. It stores the durable organization/repository/root identity separately from the last cloud activation snapshot. The snapshot records its exact target commit and immutable manifest identity. Moving a branch or checking out another commit does not unlink the repository: status reports link, checkout relation, cloud-snapshot currency, local-gate readiness, and cloud-target readiness independently. A checkout two commits behind main can remain linked, locally gate-ready, and eligible for cloud intake at its exact older SHA. An unpushed or diverged checkout remains linked and locally usable, but cloud-backed work requires a push or an explicit appropriate branch. EvalGate never substitutes the remote branch head for the local target commit. The CLI uses %APPDATA%\evalgate\config.json on Windows, ~/Library/Application Support/evalgate/config.json on macOS, and ${XDG_CONFIG_HOME:-~/.config}/evalgate/config.json on Linux. An absolute EVALGATE_CONFIG_HOME may override that directory in managed environments. Repository configuration cannot provide a bearer key or redirect a saved session to another origin. Alternate trusted origins must use HTTPS, except localhost and loopback development. For CI and direct API clients, create a least-privilege API key in the dashboard and inject it as EVALGATE_API_KEY through the platform’s secret store. Never commit it or pass it on the command line. If the agent does not already have an admin key, it can initiate a human-approved handoff without automating the browser:
Show the returned verification_uri and user_code to an organization admin. After the admin signs in with GitHub or Google and approves the exact scopes, poll POST /api/agent-setup/poll at the advertised interval. The resulting 90-day API key is returned once. Starting or polling a request never creates an anonymous account or key. See the agent authentication guide. Standards-based CLI clients may use the RFC 8628 adapter instead: discover /.well-known/oauth-authorization-server, start at /oauth/device/authorization with public client evalgate-agent, and poll the advertised /oauth/token endpoint. Approval returns a cli_session credential whose effective role follows the approving user’s current organization membership. It is not an automation API key and link never replaces it. MCP hosts that support OAuth authorization code can instead dynamically register a public client at /oauth/register, then follow the advertised /oauth/authorize endpoint with an exact registered redirect URI and PKCE S256. The signed-in person selects the accountable organization and approves the requested scopes. Codes are single-use and expire after five minutes; access tokens expire after 90 days and can be submitted to /oauth/revoke. EvalGate does not issue a client secret or refresh token. For a safe post-approval test, call MCP server/discover, public schema-only tools/list, then authenticate and call read-only project.plan. Those MCP operations invoke no model provider and no billable hosted evaluation. See the MCP request example. evalgate gate --offline separately blocks EvalGate’s built-in/configured provider-backed checks. Custom project code can still use the network, and hard network denial for wrapped commands depends on Linux unshare. Neither path is a production-like sandbox.

​
Use the API key in HTTP requests

Include your API key as a Bearer token in the Authorization header:
The base URL for all API endpoints is https://evalgate.com.

​
Configure environment variables

Store credentials as environment variables so neither the SDK nor your code needs to hardcode them.
.env
Both variables are required for SDK workflows that create org-scoped platform resources. Direct REST API routes derive the organization from the API key unless an endpoint explicitly documents an organizationId field.

​
SDK auto-loading

Both the TypeScript and Python SDKs read EVALGATE_API_KEY and EVALGATE_ORGANIZATION_ID automatically when you call .init() with no arguments.
If you need to pass credentials explicitly, pass them directly to the constructor:

​
Authentication errors

If a request fails with 401 Unauthorized, check that:
  • The Authorization header is present and formatted as Bearer YOUR_API_KEY.
  • The key was copied in full.
  • The key has not been deleted from the Developer Dashboard.
  • The key scopes include the operation you’re attempting.

​
Security best practices

Treat your API key like a password. Anyone who has it can make requests on behalf of your organization.
Never commit keys to version control. Add .env to your .gitignore file before creating it:
Use CI secret stores for CI pipelines. In GitHub Actions, store credentials as repository secrets:
Create separate keys per environment. Use one key for local development, a separate key for staging, and another for production. Rotate keys when team members leave. Revoke keys for former team members immediately from the Developer Dashboard and issue new keys to active users. Provider credentials have a separate lifecycle. Store, rotate, and revoke them from provider settings, and also revoke them at the upstream provider. EvalGate stores organization provider credentials encrypted before use and does not return the plaintext credential after creation.

​
Rate limits

All API keys are subject to rate limits. If your integration receives 429 Too Many Requests, see the rate limits reference for per-plan limits and backoff guidance.