# Twelve Data auth.md — Authentication

The REST API uses API key authentication. The hosted MCP server additionally supports OAuth 2.1 (see below).

## Getting an API key

1. Register at https://twelvedata.com/register — the Basic plan is free and requires no credit card.
2. Your API key is shown in the dashboard: https://twelvedata.com/account/api-keys

## Using the API key

The REST API base URL is `https://api.twelvedata.com`. Pass the key in one of two ways:

As a query parameter:

```
GET https://api.twelvedata.com/price?symbol=AAPL&apikey=your_api_key
```

Or as a header:

```
Authorization: apikey your_api_key
```

The WebSocket endpoint `wss://ws.twelvedata.com` and the hosted MCP server `https://mcp.twelvedata.com` use the same API key.

## MCP server (OAuth)

The hosted MCP server at `https://mcp.twelvedata.com/mcp` supports OAuth 2.1
in addition to API keys. MCP clients (Claude, ChatGPT, etc.) can authorize
interactively — authorization code flow with PKCE, refresh tokens, and dynamic
client registration (RFC 7591) are supported.

- Authorization server metadata (RFC 8414): https://mcp.twelvedata.com/.well-known/oauth-authorization-server
- Protected resource metadata (RFC 9728): https://mcp.twelvedata.com/.well-known/oauth-protected-resource/mcp

OAuth applies to the MCP server only; the REST API at `https://api.twelvedata.com`
uses API keys.

## Agent registration (Dynamic Client Registration)

Agents can self-register an OAuth client on the MCP server without human
involvement via Dynamic Client Registration (RFC 7591):

```
POST https://mcp.twelvedata.com/register
Content-Type: application/json

{
  "client_name": "my-agent",
  "redirect_uris": ["https://agent.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "client_secret_post"
}
```

The response contains `client_id` and `client_secret`. Then run the standard
authorization code flow with PKCE against the endpoints listed in
https://mcp.twelvedata.com/.well-known/oauth-authorization-server
(`authorization_endpoint`, `token_endpoint`; scope: `twelvedata`).
Tokens can be revoked at the `revocation_endpoint`.

Registration is anonymous — no account is required to obtain a client. To claim
the credentials for a human-owned account (and manage API keys, plans, and
limits), register at https://twelvedata.com/register.

## Errors and limits

- `401` — missing or invalid API key.
- `429` — rate limit exceeded; request frequency and credit limits depend on the plan (see https://twelvedata.com/pricing).
- Most endpoints cost 1 API credit per symbol; premium data (fundamentals, analysis) costs more.

## More information

- Documentation: https://twelvedata.com/docs
- Documentation for LLMs: https://twelvedata.com/docs/llms.txt
- OpenAPI specification: https://api.twelvedata.com/doc/swagger/openapi.json
- API catalog: https://twelvedata.com/.well-known/api-catalog