# Docs

- [Orbital Gateway](/docs): Product and implementation docs for the Orbital Gateway integration platform.

# Orbital Gateway

Orbital Gateway is the integration control plane for managed agent platforms.

It separates public docs, authenticated workspace configuration, Runtime API,
Connect API, Management API, and provider callbacks into one production route
surface.

## Core surfaces

- Runtime API: command discovery, schemas, execution, and execution lookup.
- Connect API: client-facing integration discovery and connection setup.
- Management API: platform administration for workspaces, environments, projects, and clients.
- Callbacks: opaque OAuth and webhook ingress URLs backed by durable records.

## Concepts

Orbital Gateway models platform configuration with four primary scopes.

- Workspace: the top-level administrative boundary.
- Environment: a deployable or customer boundary inside a workspace.
- Project: the runtime boundary for integrations, connections, clients, and executions.
- Client: the machine identity used by an agent, API, MCP server, or service to call Runtime and Connect APIs.

## Runtime API

The Runtime API is the command surface used by agents and other clients.

```text
GET  /api/v1/runtime/discovery
POST /api/v1/runtime/schemas/resolve
POST /api/v1/runtime/commands/execute
GET  /api/v1/runtime/executions/:executionId
```

Runtime calls authenticate as an Orbital client and resolve effective project
state before exposing integrations, commands, connections, and schemas.

## Connect API

The Connect API is the user-mediated setup surface for clients.

```text
GET  /api/v1/connect/integrations
GET  /api/v1/connect/integrations/:integrationKey
GET  /api/v1/connect/connections
POST /api/v1/connect/connections
POST /api/v1/connect/oauth/start
```

Connections store provider credentials through Orbital secret references.
Secrets are never returned to agents, saved views, logs, docs, or public pages.

## Management API

The Management API is the external administration surface.

```text
/api/v1/management/workspaces/*
/api/v1/management/environments/*
/api/v1/management/projects/*
/api/v1/management/clients/*
/api/v1/management/connections/*
```

Management calls use service-account authentication and operate on explicit
workspace, environment, project, and client scopes.

## Callbacks

Provider callback URLs stay top-level and opaque.

```text
GET  /callbacks/oauth/:callbackId
POST /callbacks/webhooks/:ingressId
```

Callback IDs use Orbital-generated prefixes such as `cb_` and `wh_`.

The URL does not encode integration keys, workspace slugs, project slugs,
connection IDs, or endpoint keys. Orbital resolves that context from durable
callback and webhook ingress records.

## Local deployment

Use the local Docker scripts during development.

```bash
pnpm docker:local:dev
pnpm docker:local:build
```

The web app owns public pages, docs, login, and the authenticated console under
`/w`. The gateway owns `/api/v1/*` and `/callbacks/*`.