> ## 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 and directory access in Orbit Search

> Organizations own your directories, sources, access grants, and API keys. Learn when to use org keys vs. personal keys.

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:

```json theme={"dark"}
{
  "query": "festival programmers",
  "numUsers": 10,
  "searchScope": { "type": "directory", "directoryId": "DIRECTORY_UUID" }
}
```

Multiple directories:

```json theme={"dark"}
{
  "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

| Capability                                                          | Organization 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 keys                            | No — manage keys in the dashboard |
| Call the API key usage endpoint                                     | No — 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.

<Tip>
  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.
</Tip>

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