Authentication

The Gumloop API supports two authentication methods. Both grant the same permissions and work on every endpoint. Pick whichever matches how your app gets the credential.

API key

For scripts and integrations you control end to end. Generate a personal key in the Gumloop API key row of your Profile settings page. To get there, open Settings at the bottom of the left sidebar, then Profile. Pass the key as a bearer token. For step-by-step help, see Find your Gumloop API key.

curl https://api.gumloop.com/api/v1/start_agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "xxxxxxxxxxxx", "gummie_id": "xxxxxxxxxxxx", "message": "Hello"}'

Personal vs team keys

Gumloop has two kinds of API key, and each one lives on the settings page of whoever owns it:

Personal key: the Gumloop API key row on your Profile settings page.
Team key: the Gumloop API key row on the team’s Team Overview page. In the left sidebar, right-click the team under Teams and choose Settings. Org admins can also open Settings, choose Teams under People & Access, and select the team. Team members can view and copy the key. Only team admins can generate, regenerate, or revoke it.

	Personal key	Team key
Acts as	The owning user only	Any team member (set `user_id` per request)
Default credentials	Your personal credentials	The credentials configured per workflow step (`Personal Default` or `Team Default`)
Use when	Solo use, local development	Team automations, server-to-server, CI/CD

When a request includes project_id, each workflow step’s Credentials to use setting decides whether the run uses the calling user’s personal credentials or the team’s credentials.

The API parameter is still named project_id for backwards compatibility. It’s the same thing the UI now calls your team ID.

You can find your user_id in the User ID row of the Profile settings page, just above Gumloop API key. See Finding your user ID for details.

OAuth 2.0

If you’re building an app that other Gumloop users sign in to, use OAuth 2.0. Once you’ve completed the flow and have an access token, pass it the same way:

curl https://api.gumloop.com/api/v1/agents \
  -H "Authorization: Bearer ACCESS_TOKEN"

OAuth access to the Gumloop API requires the Pro plan or above. A token for an account below Pro is refused with 403 and the error tier_required_pro. API keys do not have this plan check.

Core concepts

Agents

Sessions

Skills

Artifacts

MCP

Browser profiles

Evaluations

Organization evaluations

Brain

Teams

Models

File operations

Enterprise organization

API key

Personal vs team keys

OAuth 2.0

​API key

​Personal vs team keys

​OAuth 2.0

API key

Personal vs team keys

OAuth 2.0