Skip to main content
Every Skyvern credential is scoped to one organization. There are two ways to authenticate, and both resolve to the same thing: full API access on behalf of that organization.

​
API keys

An API key is an organization-scoped bearer credential. Send it in the x-api-key header:
Find and copy your key from Settings in the Cloud dashboard, or at app.skyvern.com/settings.

​
What an API key can do

The key identifies the organization it belongs to. Authorization is at that granularity and no finer:
  • It can call every documented endpoint that the organization can reach — create and cancel runs, read run history and artifacts, create and delete workflows, manage browser sessions and profiles, and read and write stored credentials.
  • Usage and cost are metered to that organization.
  • It carries no expiry of its own; it is valid until revoked.
There are no read-only keys, per-endpoint keys, or per-resource keys today. Any API key grants full organization-level authority, so treat one like a root password: store it in a secrets manager, never commit it, and never ship it to a browser or mobile client.

​
Isolating access

Because scoping is per organization, the organization is the isolation boundary. To separate access:
  • Use separate organizations for separate blast radii — production versus staging, or one per customer or per team.
  • Rotate keys from Settings when someone with access leaves or a key may have leaked. Revoking a key immediately invalidates every client using it, including OAuth tokens issued against it.
  • Put outbound results behind webhooks with signature verification rather than handing a key to a third party so it can poll.

​
OAuth 2.0

Skyvern Cloud is an OAuth 2.0 authorization server, backed by Clerk. It exists so MCP clients and AI assistants can authenticate a human with a browser sign-in instead of asking them to paste a static key into a config file. Discovery metadata is public:
Clients that support MCP OAuth discovery — Claude Code, Claude Desktop, Cursor, Codex CLI, ChatGPT — need no client ID or client secret in their config; they register dynamically and open a browser for sign-in. See the MCP server setup guide for per-client commands.

​
Supported scopes

The authorization server advertises these scopes_supported: The protected-resource metadata for the MCP server narrows the advertised set to profile and email.
These are identity scopes, not API permission scopes. They describe which claims about the signed-in user the token carries. They do not restrict which Skyvern endpoints or tools the token can reach.
Once the authorization code is exchanged, the resulting access token authorizes as the organization the signed-in user belongs to, with the same organization-wide authority as an API key. Requesting fewer scopes does not produce a more restricted token. Access tokens expire and are refreshable with offline_access; a refresh token is single-use and rotated on every exchange, and replaying an old one revokes the whole token family. Revoking the organization’s API key also invalidates tokens issued against it.

​
MCP server

The hosted Model Context Protocol server is at https://api.skyvern.com/mcp. It accepts either credential:
  • OAuth: Authorization: Bearer <access_token>
  • API key: x-api-key: YOUR_API_KEY
You can narrow the tool list a client sees, either with a scoped URL or a header:
Valid values are operate, build, browser, lean, and all. Omitting the scope is identical to all.
Tool scopes are a usability filter, not an authorization boundary. They change which tools the server advertises, so a smaller scope means a smaller, sharper tool list for the model — but the request still authenticates with the same organization-wide credential. Do not rely on a narrow scope to prevent a client from taking an action.

​
Summary of the scoping model

  • Organization is the only authorization boundary. Every credential is bound to exactly one, and grants full access within it.
  • API keys are org-scoped bearer credentials with no sub-scopes, sent as x-api-key.
  • OAuth scopes control identity claims about the signed-in user, not API reach.
  • MCP tool scopes control the advertised tool catalog, not permissions.
  • To limit what a credential can touch, create a separate organization.

API Key

Find, copy, and rotate your key in the Cloud dashboard

MCP Server

Per-client OAuth and API-key setup for the hosted MCP server