Authentication

Every Studio API request uses a scoped bearer key tied to one GearDex account and integration.

StudioThe Studio API, webhooks, and MCP adapter are included with the Studio plan.Compare plans

Bearer authentication

Send your key in the Authorization header on every request. GearDex validates the key, subscription access, expiration, revocation status, rate limit, requested scope, and resource ownership before returning Studio data.

Create a key

Sign in and open Settings, then API & Agents.
Choose a name that identifies the service using the key.
Select the minimum required scopes.
Set an expiration date appropriate for the integration.
Copy the key once and store it in your secret manager.

Request example

The bearer token belongs in the header, not in a query string or JSON body.

bashRequest (cURL)

curl -X GET "https://www.geardex.app/api/studio-agent/v1/gear?limit=3" \
  -H "Authorization: Bearer gdx_live_your_key_here" \
  -H "Accept: application/json"

jsRequest (JavaScript)

const response = await fetch("https://www.geardex.app/api/studio-agent/v1/gear?limit=3", {
  headers: {
    Authorization: `Bearer ${process.env.GEARDEX_STUDIO_API_KEY}`,
    Accept: "application/json",
  },
})

if (!response.ok) {
  throw new Error(`GearDex request failed: ${response.status}`)
}

const payload = await response.json()

Key lifecycle

Use one key per application, agent host, or automation.
Prefer short, explicit expiration windows.
Rotate secrets without changing the integration's scope model.
Revoke a key immediately when a machine or service is retired.
Review activity logs for unexpected endpoints or request volume.

Authentication errors

GearDex authentication error responses
Status and code	Kind	Meaning
401 missing_authorization	authentication	The request did not include a Bearer authorization header.
401 key_not_found	authentication	The key is invalid, unknown, or no longer available.
401 key_revoked	authentication	The Studio owner revoked this integration key.
401 key_expired	authentication	The key passed its configured expiration date.
403 insufficient_scope	authorization	The key is valid but cannot perform the requested operation.
429 rate_limited	rate limit	Back off and respect the Retry-After response header.

The full list of codes lives in Responses and errors.