> For the complete documentation index, see [llms.txt](https://docs.orbitfin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbitfin.ai/orbit-api-reference/overview/authentication.md).

# Authentication

### 1. Overview <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--1-overview-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--1-overview-0"></a>

Orbit exposes two access channels, both of which require authentication:

* **REST API** — for backend services, data pipelines, and batch jobs.
* **MCP (Model Context Protocol) Server** — for AI agents and LLM clients such as Claude, ChatGPT, and Cursor.

To support both machine-to-machine integrations and end-user delegated access, Orbit supports **two authentication methods**:

<table><thead><tr><th>Method</th><th>Channels</th><th>Typical Use Cases</th><th data-hidden></th></tr></thead><tbody><tr><td><strong>API Key</strong></td><td>REST API </td><td>Server-to-server calls, individual developers, trusted internal environments</td><td></td></tr><tr><td><strong>OAuth 2.0 / 2.1</strong></td><td>REST API, MCP (remote HTTP)</td><td>Third-party app integrations, end-user delegated access, AI agent remote tool calls</td><td></td></tr></tbody></table>

### 2. Base URLs & Interactive References <a href="#heading-f20e82ae-0d17-4395-8fc6-21abfe6b1b51--20-base-urls-interactive-references-0" id="heading-f20e82ae-0d17-4395-8fc6-21abfe6b1b51--20-base-urls-interactive-references-0"></a>

Before issuing any request, make sure you are calling the correct endpoint. Orbit exposes two independent services, each with its own base URL and interactive documentation:

| Service        | Base URL                             | Interactive Reference                                                       | Description                                                                                                                             |
| -------------- | ------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **REST API**   | `https://api.orbitfin.ai`            | `https://api.orbitfin.ai/docs` [<sup>1</sup>](https://api.orbitfin.ai/docs) | RESTful endpoints for programmatic access — entity lookup, report retrieval, file download, PDF parsing, news, EOD price, Chat AI, etc. |
| **MCP Server** | `https://mcp.orbitfin.ai/server/mcp` | `https://mcp.orbitfin.ai/docs` [<sup>2</sup>](https://mcp.orbitfin.ai/docs) | Streamable HTTP MCP endpoint for LLM clients (Claude Code, ChatGPT, Cursor, …) following the Model Context Protocol specification.      |

This API Reference describes the RESTful and realtime APIs you can use to interact with the Orbit platform. REST APIs are usable via HTTP in any environment that supports HTTP requests.

**Quick Reference**

**REST API**

```
<HTTP>
Base URL:         https://api.orbitfin.ai      
OpenAPI / Docs:   https://api.orbitfin.ai/docs
Auth Header:      X-API-KEY: <your-api-key>
Versioning:       /v1/...   (e.g. /v1/company_report/file_list)
Content-Type:     application/json
```

**MCP Server**

```
<HTTP>
Endpoint:         https://mcp.orbitfin.ai/server/mcp
Transport:        Streamable HTTP (MCP spec)
Docs:             https://mcp.orbitfin.ai/docs
Auth (API Key):   X-API-KEY: <your-api-key>
Auth (OAuth):     Authorization: Bearer <access_token>   ← see §3
```

**Minimal Smoke Tests**

Verify your key works against each surface in under 10 seconds.

**① REST API — list files for a report**

```
curl -X POST 'https://api.orbitfin.ai/v1/company_report/file_list' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "report_id": ["f_haBmMwT4WN7tXrt8rj9eA3"],
        "option": ["pdf"]
      }'
```

Obtain different types of file information based on a list of report IDs and query options.

Full request/response schemas and a live "Try it out" console are available in the API Playground [<sup>1</sup>](https://api.orbitfin.ai/docs).

**② MCP Server — connect via JSON config**

```
{
  "mcpServers": {
    "orbit": {
      "url": "https://mcp.orbitfin.ai/server/mcp",
      "headers": {
        "X-API-KEY": "<your-api-key>"
      }
    }
  }
}
```

For the full list of MCP tools, resources, and prompt templates exposed by the server, browse the interactive catalog at `https://mcp.orbitfin.ai/docs` [<sup>2</sup>](https://mcp.orbitfin.ai/docs).

**Unified Billing Across Both Surfaces**

API Key usage on either surface draws from the **same credit pool** on your Orbit account:

Universal Currency: Same credits work for both APIs and MCP · APIs: Direct programmatic access charges credits per operation · MCP: Natural language queries consume credits based on complexity · Shared Pool: API and MCP usage draws from the same credit balance

. There is no need to provision separate quotas — a single API key (or a single OAuth-authenticated user, see §3) is billed uniformly.

<br>

### 3. Method 1: API Key Authentication <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--2-method-1-api-key-authentication-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--2-method-1-api-key-authentication-0"></a>

1. Sign in to the Orbit Console\[<https://insight.orbitfin.ai/>] → **Settings → API Keys**.

<figure><img src="/files/Q2qQEI3se4Oq8e2XVL7h" alt=""><figcaption></figcaption></figure>

2. Click **Create API Key**, give it a name, and save.

#### 3.2 Using API Key with the REST API <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--22-using-api-key-with-the-rest-api-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--22-using-api-key-with-the-rest-api-0"></a>

Pass the key in the `X-API-KEY` header:

**\<BASH>**

```
curl -X POST 'https://api.orbitfin.ai/v1/company_report/file_list' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "report_id": ["f_haBmMwT4WN7tXrt8rj9eA3"],
        "option": ["pdf"]
      }'
```

#### 3.3 Using API Key with MCP <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--23-using-api-key-with-mcp-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--23-using-api-key-with-mcp-0"></a>

For local stdio MCP clients or trusted environments:

**\<JSON>**

```
{
  "mcpServers": {
    "orbit": {
      "url": "https://mcp.orbitfin.ai/server/mcp",
      "headers": {
        "X-API-KEY": "<your-api-key>"
      }
    }
  }
}
```

#### 3.4 Security Best Practices <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--24-security-best-practices-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--24-security-best-practices-0"></a>

API keys are long-lived credentials that do not carry user identity, which makes per-user authorization difficult and creates significant risk if leaked into logs or version control; audit trails can only record what an API key did, not which user.

Therefore:

* **Never** embed API keys in frontend code.
* **Never** commit them to Git.
* **Rotate** keys regularly.
* Follow the **principle of least privilege** when assigning scopes (where supported).

### 4. Method 2: OAuth 2.0 Authentication (Recommended for MCP & Third-Party Apps) <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--3-method-2-oauth-20-authentication-recommended-for-mcp" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--3-method-2-oauth-20-authentication-recommended-for-mcp"></a>

#### 4.1 When to Use OAuth 2.0 <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--31-when-to-use-oauth-20-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--31-when-to-use-oauth-20-0"></a>

* Third-party SaaS applications integrating with Orbit.
* AI agents / LLM clients calling Orbit tools via remote MCP.
* Any scenario that requires **end-user identity** rather than application identity, with a complete audit trail.

#### 4.2 Calling the MCP with an Access Token <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--33-calling-the-api-with-an-access-token-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--33-calling-the-api-with-an-access-token-0"></a>

**\<JSON>**

```
{
  "mcpServers": {
    "orbit": {
      "url": "https://mcp.orbitfin.ai/server/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}
```

#### 4.3 OAuth Configuration for the Remote MCP Server <a href="#heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--34-oauth-configuration-for-the-remote-mcp-server-0" id="heading-17e4230e-4444-4c7c-bcc1-f83210b378ef--34-oauth-configuration-for-the-remote-mcp-server-0"></a>

When integrating with MCP-aware clients (Claude Desktop, ChatGPT, etc.), Orbit's MCP Server exposes the standard discovery endpoints:

* [`https://mcp.orbitfin.ai/.well-known/oauth-protected-resource`](https://mcp.orbitfin.ai/.well-known/oauth-authorization-server) — Resource metadata

On first connect, the client automatically discovers these endpoints and initiates the OAuth flow.

After the OAuth flow completes, the client attaches the obtained access token via the `Authorization: Bearer …` header on subsequent MCP requests. The server must treat the token as untrusted and perform full resource-server validation: signature verification, issuer/audience checks, expiration, replay protection, and scope enforcement.

#### 4.4 Connecting Orbit MCP in Claude Code & ChatGPT <a href="#heading-a084401b-d733-4c25-b6ad-16800c464428--36-connecting-orbit-mcp-in-claude-code-chatgpt-0" id="heading-a084401b-d733-4c25-b6ad-16800c464428--36-connecting-orbit-mcp-in-claude-code-chatgpt-0"></a>

Thanks to OAuth 2.0 + DCR, end users **do not need to manually create an API key or paste any token**. The entire setup is just three steps:

**▶ Claude Code**

1. Open **Claude Code → Settings → Connectors → Add Custom Connector**.
2. Fill in the form:
   * **Name**: any name you like, e.g. `Orbit`
   * **Remote MCP server URL**: `https://mcp.orbitfin.ai`
3. Click **Add**. Claude Code will automatically:
   * Discover Orbit's `.well-known` OAuth metadata,
   * Register itself via Dynamic Client Registration,
   * Open a browser window to the Orbit Insight login page.
4. Enter your **Insight platform username and password** to authorize.
5. Done ✅ — the Orbit tools are now available inside Claude Code.

> Example configuration (as shown in the screenshot):
>
> ```
> <TEXT>Name:                OrbitRemote MCP server URL: 
> https://mcp.orbitfin.ai/.well-known/oauth-protected-resource
> ```

**▶ ChatGPT**

1. Open **ChatGPT → Settings → Connectors → Create**(or **Add custom connector** in the Developer Mode panel).
2. Fill in:
   * **Name**: `Orbit` (or any name you prefer)
   * **MCP Server URL**: <https://mcp.orbitfin.ai/server/mcp>
   * **Authentication**: select **OAuth**
3. Click **Create / Connect**. ChatGPT will redirect you to the Orbit Insight login page.
4. Sign in with your **Insight platform username and password** to grant access.
5. Done ✅ — Orbit tools appear in ChatGPT's tool list and can be invoked in conversations.

**Why it's this simple**

* Orbit's MCP server publishes OAuth discovery metadata at\
  `https://mcp.orbitfin.ai/.well-known/oauth-protected-resource`
* Clients (Claude Code / ChatGPT) auto-register via **Dynamic Client Registration**, so no `client_id` / `client_secret` setup is required by the user.
* The user only authenticates **once** with their existing Insight account; refresh tokens keep the session alive.

<figure><img src="/files/pWBDoZc2Mj9kwB9cXGQP" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.orbitfin.ai/orbit-api-reference/overview/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.