# 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

The API and [MCP server](/docs/api/mcp) share these default request limits:

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

Each person has one allowance within each workspace, shared across their authorized AI clients and credentials. Each unattended API key has its own allowance, which continues through key rotation.

Requests count in fixed one-minute and one-hour windows, including MCP setup, discovery, and tool calls. The response headers show the allowance applied to your request:

| 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 either limit, the service returns `429 Too Many Requests` with an error envelope of type `rate_limited`. Wait at least the number of seconds in `Retry-After` before making another request. The delay covers every exhausted window, and `X-RateLimit-Reset` gives its reset timestamp. Repeated attempts count toward the same fixed windows.

For a temporary service interruption, a `503 Service Unavailable` response includes retry guidance. Follow `Retry-After` before trying again.

## 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 |
| `service_unavailable` | 503 | Temporary service interruption; follow `Retry-After` before retrying |

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