> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gabin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys for your code, OAuth 2.1 for MCP connectors. Every call to /v1 carries a Bearer token.

Every endpoint under `https://api.gabin.ai/v1` requires an `Authorization: Bearer <token>` header, except `GET /v1/health` and `GET /v1/openapi.json`. The token is either an **API key** or an **OAuth access token**. Both are tied to your account: same limits, same quota, same usage page.

```bash theme={null}
curl "https://api.gabin.ai/v1/me" -H "Authorization: Bearer $GABIN_API_KEY"
```

## API keys

Use an API key from your own code, scripts and servers, and from MCP clients that accept a header (Claude Code, Cursor, VS Code).

* **Create** a key at [gabin.ai/compte/api](https://gabin.ai/compte/api). Your account needs a verified email: an account created with GitHub or Google has one; an email-and-password account gets a verification link.
* **Format**: `gab_live_` followed by 43 characters. The key is shown once; Gabin stores only a hash of it, so a lost key cannot be recovered. Create a new one.
* **Up to 5 active keys** per account. Name them by use (`prod`, `staging`, `laptop`) so you can revoke one without breaking the others.
* **Revoke** a key from the same page. It stops working within a minute.

> [!WARNING]
>
> A key gives access to your account and its quota. Keep it server-side: in an environment variable or a secret manager, never in front-end code, a public repository or a mobile app. To use Gabin from a browser (for example [map tiles](https://docs.gabin.ai/guides/tiles.md)), call it through your own backend.

## OAuth 2.1 (MCP connectors)

Assistants such as Claude and ChatGPT connect to the [MCP server](https://docs.gabin.ai/mcp/overview.md) with OAuth: you add the server URL, sign in to Gabin, and approve the access on a consent screen. You never paste a key.

| | |
| - | - |
| Authorization server (issuer) | `https://gabin.ai` |
| Metadata | `https://gabin.ai/.well-known/oauth-authorization-server` (RFC 8414) |
| Protected resource metadata | `https://mcp.gabin.ai/.well-known/oauth-protected-resource` (RFC 9728) |
| Client registration | Dynamic (RFC 7591), public clients |
| Grant | Authorization code with PKCE (`S256` required) |
| Resource indicator | `https://mcp.gabin.ai` or `https://api.gabin.ai` (RFC 8707) |
| Scope | `read` |
| Access token | `gat_…`, valid 1 hour |
| Refresh token | `gar_…`, valid 30 days, rotated at each use |
| Revocation | `https://gabin.ai/oauth/revoke` (RFC 7009) |

The consent screen shows the domain that will receive the access. Approve only an application you have just connected yourself. You can see and revoke authorized applications at [gabin.ai/compte/api](https://gabin.ai/compte/api), under **Applications autorisées**; revoking cuts the access immediately.

An OAuth access token also works on the REST API, with the same limits as your keys.

## When authentication fails

| Situation | Response |
| - | - |
| No `Authorization` header | `401 UNAUTHENTICATED` |
| Unknown, revoked or expired token | `401 UNAUTHENTICATED` |
| Too many invalid tokens from one IP address (30 per minute) | `429 RATE_LIMITED` for invalid tokens only; a valid token still goes through |

On the MCP server, a missing or refused token returns `401` with a `WWW-Authenticate` header that points to the protected resource metadata, which is how MCP clients start the OAuth flow. See [errors](https://docs.gabin.ai/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.