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

# Organizations & Teams

> Manage organization resources, projects, keys, and team access

Everything in Runtools belongs to an organization — sandboxes, agents, tools, secrets, API keys, SSH keys, projects, and workspaces all live under one. People sign in to the dashboard and CLI through WorkOS sessions; code authenticates with API keys minted inside the org.

## Members And Roles

The dashboard Team page is the primary member-management surface.

| Role   | Access                                                                     |
| ------ | -------------------------------------------------------------------------- |
| Admin  | Organization settings, broader org views, shared resources, and publishing |
| Member | Own and use resources allowed by organization policy                       |

Admin-only API options include broader views such as `--all-org`, org-shared secret writes, and publishing tools or agents to organization or public visibility.

## Projects

Projects organize resources inside an organization. They are a filtering and grouping layer; permissions remain organization/member based.

Project APIs are available under:

```text theme={null}
https://api.runtools.ai/v1/projects
```

Common project-owned or project-filtered resources include agents, sandboxes, API keys, and SSH keys.

## Workspaces

Workspaces are persistent storage spaces owned by the organization.

```bash theme={null}
curl https://api.runtools.ai/v1/workspaces \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

Organization workspaces can be mounted into sandboxes and used as persistent filesystem memory for agents attached to those sandboxes:

```typescript theme={null}
await rt.sandbox.create({
  template: 'base-ubuntu',
  mounts: [
    {
      workspaceId: '9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e',
      path: '/workspace',
    },
  ],
});
```

Personal workspaces are owner/admin scoped and cannot be mounted into sandboxes.

## API Keys

Create API keys from the dashboard or CLI:

```bash theme={null}
runtools auth keys list
runtools auth keys create "production-api" --scope "*"
runtools auth keys revoke <key-id>
runtools auth keys rotate <key-id> --name "rotated-production-api"
```

Use keys with the SDK:

```typescript theme={null}
import { RunTools } from '@runtools-ai/sdk';

const rt = new RunTools({
  apiKey: process.env.RUNTOOLS_API_KEY,
});
```

Common scopes include:

| Scope       | Access                            |
| ----------- | --------------------------------- |
| `*`         | Full API key access               |
| `sandbox:*` | Sandbox lifecycle and execution   |
| `agent:*`   | Agent management and runs         |
| `agent:run` | Run agents                        |
| `tool:*`    | Tool Hub management and execution |
| `files:*`   | Workspace file access             |
| `ssh-key:*` | SSH key management                |

<Warning>
  API key values are shown once. Store them in a secret manager and rotate keys after team or deployment changes.
</Warning>

## SSH Keys

```bash theme={null}
runtools ssh-key list
runtools ssh-key add personal-laptop --file ~/.ssh/id_ed25519.pub
runtools ssh-key set-default <id>
```

SSH keys can be user-private or org-wide depending on the flags used when adding them.

## Secrets

```bash theme={null}
runtools secret set ANTHROPIC_API_KEY "sk-ant-xxx" --category provider
runtools secret set SHARED_CRM_KEY "crm_xxx" --category tool --org-wide
runtools secret list --org-only
```

Secrets are user-private by default. Org-shared secrets require the appropriate admin policy.

See [Secrets & Credentials](/advanced/secrets) for API and SDK examples.

## OAuth Connections

Connected Apps are scoped to the authenticated user and organization context.

```bash theme={null}
runtools oauth connect github
runtools oauth status
runtools oauth set-default <connection-id>
```

Tool Hub uses connected apps during server-side credential resolution when a tool declares an OAuth provider.

## Best Practices

<AccordionGroup>
  <Accordion title="Use projects for navigation, not isolation">
    Projects keep resources tidy, but access control is enforced at the organization/member/resource level.
  </Accordion>

  <Accordion title="Create narrow API keys">
    Use scopes that match the integration. CI jobs often need fewer scopes than an operator key.
  </Accordion>

  <Accordion title="Separate user-private and org-shared secrets">
    Use org-wide secrets only for credentials meant to be shared by the team.
  </Accordion>

  <Accordion title="Use all-org flags deliberately">
    `--all-org` surfaces are intended for admins doing organization-level review or support.
  </Accordion>
</AccordionGroup>