# Authentication

Source: https://www.geardex.app/api-docs/authentication

API access requires the GearDex Studio plan and a scoped Studio API key.

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

## 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.

Server-side only

A Studio API key is a secret. Do not place it in a browser bundle, mobile binary, public repository, client-visible environment variable, or analytics payload.

## Create a key

1. [Sign in](https://www.geardex.app/signin) and open **Settings**, then **API & Agents**.
2. Choose a name that identifies the service using the key.
3. Select the minimum required [scopes](https://www.geardex.app/api-docs/scopes).
4. Set an expiration date appropriate for the integration.
5. Copy the key once and store it in your secret manager.

Key format

Live Studio keys begin with  `gdx_live_` . GearDex stores a secure hash rather than the original secret.

## Request example

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

**Request (cURL)**

```bash
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"
```

**Request (JavaScript)**

```js
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](https://www.geardex.app/api-docs/audit-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](https://www.geardex.app/api-docs/errors).