# Authentication and the MCP endpoint

The Connector Central API is a RESTful JSON API for verifying credentials and inspecting the workspace bound to a token.

> **Interactive reference:** The full API specification with request/response schemas and a built-in "Try it out" tool lives at the [interactive API reference](/api/v1/docs.html). The raw OpenAPI spec is at [`/api/v1/openapi.yaml`](/api/v1/openapi.yaml). This page is a narrative overview -- use the interactive reference for endpoint-level details.

## Base URL

All API endpoints are available at:

```
https://connectorcentral.com/api/v1/
```

## Authentication

Every request must include an `Authorization` header with a Bearer token:

```
Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN
```

Applications that act on behalf of a user obtain tokens through the **OAuth 2.0 authorization code grant**. Connector Central provides authorize, token, revoke, and introspect endpoints under `/oauth`, dynamic client registration (RFC 7591) at `POST /oauth/register`, and discovery documents at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`. During authorization the user picks which workspace to connect, and the issued access and refresh tokens are scoped to it.

Groups and API keys are included in the Growth and Enterprise plans. See [pricing](/pricing).

On Growth and Enterprise plans, admins and owners can also create an [API key](/docs/api/api-keys). It is a workspace-bound bearer credential that authenticates directly in the same Bearer header. It is not an OAuth client ID or client secret and does not perform discovery, browser consent, token exchange, or refresh.

### Scopes

Tokens carry scopes that limit which endpoints they can call:

| Scope | Grants access to |
|-------|-----------------|
| `profile:read` | Baseline read access — request this for connections that only need to identify the workspace |

`GET /api/v1/ping` and `GET /api/v1/me` accept any valid token, regardless of scope. Calling an endpoint without the required scope returns `403` with type `insufficient_scope`.

## Quick start

```bash
export ACCESS_TOKEN=REPLACE_WITH_ACCESS_TOKEN
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://connectorcentral.com/api/v1/ping
```

```json
{
  "status": "ok",
  "account": { "id": "…", "name": "Your Workspace" },
  "token": { "application": "My integration", "scopes": ["profile:read"] }
}
```

## Available endpoints

| Endpoint | Description | Required scope |
|----------|-------------|----------------|
| `GET /api/v1/ping` | Health check; returns account and token metadata | any valid token |
| `GET /api/v1/me` | The authenticated workspace's id, name, slug, and token scopes | any valid token |

## Rate limits

All authenticated API requests (including the [MCP server](/docs/api/mcp)) are rate-limited per token:

- **60 requests per minute**
- **500 requests per hour**

Every API response includes:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

When you exceed a limit you receive `429 Too Many Requests` with a `Retry-After` header and an error envelope of type `rate_limited`.

## Error format

All errors use a consistent JSON envelope:

```json
{
  "error": {
    "type": "invalid_token",
    "message": "The access token is invalid or has been revoked"
  }
}
```

| Type | Status | Meaning |
|------|--------|---------|
| `authentication_required` | 401 | Missing or malformed `Authorization` header |
| `invalid_token` | 401 | Token is unknown, revoked, or its application was revoked |
| `token_expired` | 401 | Token has expired (OAuth flows; refresh it) |
| `insufficient_scope` | 403 | Token lacks the required scope |
| `forbidden` | 403 | The credential is not permitted to call this endpoint |
| `not_found` | 404 | Resource doesn't exist in this workspace |
| `invalid_request` | 400 | Malformed request body or missing parameter |
| `validation_error` | 422 | Attributes failed validation; the message lists the failures |
| `rate_limited` | 429 | Too many requests |

## Going further

- **[Connect an AI client](/docs/connect-ai-clients/chatgpt)** — authorize a user and choose the workspace through OAuth discovery
- **[API keys](/docs/api/api-keys)** — authenticate an unattended workload and give it least-privilege connector access
- **[MCP server reference](/docs/api/mcp)** — review workspace binding, live tool discovery, revocation, and errors
- **[Interactive API reference](/api/v1/docs.html)** — schemas, examples, and a try-it-out console