Skip to main content

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.

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, 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:
ScopeWhat it grants
search:readCall the smart search endpoint (POST /v2/social/profiles/searches/smart)
profile:readFetch 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.
  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.
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.
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.

​
Making authenticated requests

Include the raw key as a bearer token on every API call: 
curl -X POST "https://api.orbitsearch.com/v2/social/profiles/searches/smart" \
  -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.
1

Issue

Issue a new key from the dashboard and immediately store the raw sk_orb_... value.
2

Use

Pass the key as Authorization: Bearer sk_orb_... on every API request.
3

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.
4

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.
Prefer revoke over delete when rotating keys in the dashboard. Revoked keys remain as auditable metadata; deleted keys are removed entirely.

​
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 statusError codeCause
401missing_api_keyRequest reached a developer-key endpoint with no Authorization: Bearer sk_orb_... header.
403invalid_api_keyKey is malformed, revoked, expired, or not recognized.
403missing_api_key_scopeKey is valid but does not include the scope required by the endpoint.
Example error response: 
{
  "status": "failed",
  "error": {
    "code": "missing_api_key_scope",
    "message": "This key does not have the required scope for this endpoint."
  }
}
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.