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

# Authenticate your requests to the Orbit Search API

> Orbit Search uses bearer token authentication with scoped API keys. Learn how to get a key, use scopes, rotate keys, and revoke old credentials.

Every request to the Orbit Search developer API must include an `Authorization` header with a bearer token. Get your first developer API key from the [Orbit developer dashboard](https://developer.orbitsearch.com/dashboard/keys), then pass that `sk_orb_...` key as the bearer token in API requests. Keys are scoped to the operations your integration needs, rate-limited, metered against your credit balance, and the raw key value is only visible once.

## Key types

Orbit Search supports two kinds of developer API keys:

**Personal keys** are tied to your user account. Credits are metered against your personal usage, and personal keys can only search the global Orbit index — they cannot target directory corpora.

**Organization keys** are tied to an organization rather than an individual. Credits are metered against the organization's credit balance. Organization keys can search named directories in addition to the global index, making them the right choice for building product integrations at scale.

## Scopes

When you issue a key in the dashboard, choose which operations it is allowed to perform:

| Scope          | What it grants                                                                                                                                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search:read`  | Call search endpoints, including Search (`POST /v2/developer/search`, `POST /v2/developer/search/sse`), Profile Query (`POST /v2/developer/profiles/:id/query`), and Developer Deep Search (`POST /v2/developer/deep-search`) |
| `profile:read` | Fetch a profile by ID (`GET /v2/developer/profiles/:id`)                                                                                                                                                                      |

A key without `search:read` will receive a `403 missing_api_key_scope` error if it attempts a search. Request only the scopes your integration actually uses.

## Getting a key

Generate and manage developer API keys in the [Orbit developer dashboard](https://developer.orbitsearch.com/dashboard/keys).

1. Sign in to Orbit.
2. Open **Dashboard** → **API keys**.
3. Choose a personal key or an organization key.
4. Select the minimum scopes your integration needs.
5. Copy the raw `sk_orb_...` key and store it in your secrets manager.

<Warning>
  The raw key is shown exactly once. Orbit stores it hashed and cannot recover it. If you close the dashboard modal without saving it, revoke that key and issue a new one.
</Warning>

<Note>
  After creation, use `display_key` (e.g. `sk_orb_a0186...55fd`) to identify a key in your UI, support tickets, or audit logs. It combines the non-secret prefix and suffix and is safe to display without exposing the raw key.
</Note>

## Making authenticated requests

Include the raw key as a bearer token on every API call:

```bash theme={"dark"}
curl -X POST "https://api.orbitsearch.com/v2/developer/search" \
  -H "Authorization: Bearer sk_orb_REDACTED" \
  -H "Content-Type: application/json" \
  -d '{"query":"founders in sf","numUsers":10}'
```

The key format is always `sk_orb_<prefix>...<suffix>`. Do not use the legacy `api-key` header — it is not supported for developer API traffic.

## Key lifecycle

The recommended lifecycle for a developer API key is: create → use → rotate → revoke.

<Steps>
  <Step title="Issue">
    Issue a new key from the dashboard and immediately store the raw `sk_orb_...` value.
  </Step>

  <Step title="Use">
    Pass the key as `Authorization: Bearer sk_orb_...` on every API request.
  </Step>

  <Step title="Rotate">
    When you need to replace a key, issue a new one first, then migrate callers one by one. Verify traffic on the new key from the dashboard usage view.
  </Step>

  <Step title="Revoke">
    Once all callers have moved to the new key, revoke the old one from **Dashboard** → **API keys**.

    Revoked keys are rejected by authentication but remain visible as inactive metadata. This preserves an audit trail for security and support reviews.
  </Step>
</Steps>

<Tip>
  Prefer revoke over delete when rotating keys in the dashboard. Revoked keys remain as auditable metadata; deleted keys are removed entirely.
</Tip>

## Listing and inspecting keys

Use the dashboard to see all your keys and their current status. Each key entry includes `display_key`, `name`, `scopes`, `created_at`, `last_used_at`, `expires_at`, `is_active`, and `is_expired`. The raw key is never shown again after creation.

## Key expiration

You can set an optional expiration when issuing a key. Expired keys are rejected by authentication and appear as expired/inactive in the dashboard. If you omit an expiration, the key does not expire unless your account has a default TTL configured.

## Error reference

When authentication fails, the API returns a machine-readable error code in the response body:

| HTTP status | Error code              | Cause                                                                                       |
| ----------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| `401`       | `missing_api_key`       | Request reached a developer-key endpoint with no `Authorization: Bearer sk_orb_...` header. |
| `403`       | `invalid_api_key`       | Key is malformed, revoked, expired, or not recognized.                                      |
| `403`       | `missing_api_key_scope` | Key is valid but does not include the scope required by the endpoint.                       |

Example error response:

```json theme={"dark"}
{
  "status": "failed",
  "error": {
    "code": "missing_api_key_scope",
    "message": "This key does not have the required scope for this endpoint."
  }
}
```

<Note>
  Developer API keys cannot create, list, revoke, or delete other API keys. For normal developer integrations, manage keys in the dashboard and use `sk_orb_...` keys only for search/profile API calls.
</Note>