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.

Organizations are the top-level ownership boundary in Orbit Search. Every directory, source, directory person, and access grant belongs to an organization. When you issue an organization API key, it is scoped to that organization — giving it the ability to search organization-owned directories that personal keys cannot reach.

​
Organization types

There are two organization types:
  • workspace — a shared organization you create for your product. Workspace organizations own directories and issue API keys that your application uses to search private corpora.
  • personal — every Orbit user automatically gets a personal organization. Your personal organization owns your Personal Connections directory and is the subject against which personal API key credits are metered.
You do not need to create a personal organization; Orbit creates it for you on sign-in.

​
Directory access grants

Directory search is always scoped to explicit directory IDs. The primitive is the directory: you grant an organization key access to one or more directories, then pass those directory IDs in searchScope. Single directory: 
{
  "query": "festival programmers",
  "numUsers": 10,
  "searchScope": { "type": "directory", "directoryId": "DIRECTORY_UUID" }
}
Multiple directories: 
{
  "query": "festival programmers",
  "numUsers": 10,
  "searchScope": {
    "type": "directories",
    "directoryIds": ["DIRECTORY_UUID_A", "DIRECTORY_UUID_B"]
  }
}

​
Organization API keys

Organization API keys are issued at the organization level from the dashboard. They are the right key type when your application needs to search private directories.

​
Creating an organization key

Open Dashboard → API keys, choose the organization that should own the key, and select the scopes your integration needs.

​
What organization keys can and cannot do

CapabilityOrganization API key
Search global profiles (global scope)Yes
Search organization directories (directory, directories scopes)Yes, with a matching grant
Create, list, revoke, or delete API keysNo — manage keys in the dashboard
Call the API key usage endpointNo — view usage in the dashboard
Credits for organization API key requests are metered against the organization subject, not the key creator’s personal account. This means usage, monthly grants, refunds, and admin adjustments are all tracked at the organization level.
Use personal API keys during development and exploration — they are simpler to issue in the dashboard and scope searches to the global public corpus. Switch to organization API keys when your application needs to search private directories or when you want usage metered against an organization rather than an individual user.

​
Credit accounting by key type

The subject that gets charged depends on the key type:
  • Personal API key → credits charged to the user’s personal subject
  • Organization API key → credits charged to the organization subject
This separation means your organization’s directory search usage does not draw from your personal monthly credit grant.

​
Key lifecycle

Both personal and organization keys use the same lifecycle: issue, use, rotate, and revoke. Manage that lifecycle in the dashboard. The raw key value is shown once at creation. Store it immediately — subsequent dashboard views only include metadata such as display_key, name, scopes, and status fields. Use display_key (for example sk_orb_a0186...55fd) to identify keys in your UI or support workflows rather than storing or displaying the raw key.