### GET /v1/install-config

Source: https://openworklabs.com/docs/api-reference/organizations/resolve-install-link-configuration

Resolves a valid install link token and returns organization setup details along with a fresh desktop connection handoff.

```APIDOC
## GET /v1/install-config

### Description
Resolves a valid install link token and returns organization setup details along with a fresh desktop connection handoff.

### Method
GET

### Endpoint
/v1/install-config

### Authentication
- **bearerAuth** - Required - Use `Authorization: Bearer <session-token>` for user-authenticated routes.
- **denApiKey** - Required - Use `x-api-key: <den-api-key>` for organization API-key calls.

### Parameters
#### Query Parameters
- **token** (string) - Required - The install link token to resolve.

### Response
#### Success Response (200)
Returns organization setup details and a fresh desktop connection handoff.

#### Response Example
```json
{
  "organization": {},
  "desktopConnection": {}
}
```

```

--------------------------------

### POST /v1/connectors/github/install/start

Source: https://openworklabs.com/docs/api-reference/github/start-github-install

Starts a GitHub App installation for the current organization by generating a redirect URL.

```APIDOC
## POST /v1/connectors/github/install/start

### Description
Builds a GitHub App install redirect URL for the current organization.

### Method
POST

### Endpoint
/v1/connectors/github/install/start

### Parameters
#### Request Body
- **returnPath** (string) - Required - The path to return to after the GitHub install completes. Must be between 1 and 1024 characters.

### Request Example
{
  "returnPath": "/settings"
}

### Response
#### Success Response (200)
- **ok** (boolean) - Always `true`.
- **item** (object) - Contains the redirect URL and state.
  - **redirectUrl** (string, uri) - The URL to redirect the user to for GitHub App installation.
  - **state** (string) - A state token to validate the callback.

#### Response Example
{
  "ok": true,
  "item": {
    "redirectUrl": "https://github.com/apps/your-app/installations/new",
    "state": "abc123"
  }
}

#### Error Responses
- **400** - The GitHub install request was invalid. Returns an `InvalidRequestError` object with `error` set to `invalid_request` and `details` array.
- **401** - The caller must be signed in to connect GitHub. Returns an `UnauthorizedError` object with `error` set to `unauthorized`.
- **403** - The caller lacks permission to connect GitHub. Returns a `ForbiddenError` object with `error` set to `forbidden` or `reauth`.

### Security
- **bearerAuth** - Session token passed as `Authorization: Bearer <session-token>`.
- **denApiKey** - Organization API key passed as the `x-api-key` header.
```

--------------------------------

### POST /v1/connectors/github/install/start

Source: https://openworklabs.com/docs/api-reference/github/start-github-install

Starts a GitHub App installation by generating a redirect URL for the current organization.

```APIDOC
## POST /v1/connectors/github/install/start

### Description
Builds a GitHub App install redirect URL for the current organization.

### Method
POST

### Endpoint
/v1/connectors/github/install/start

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **redirectUrl** (string) - The URL to redirect the user to for installing the GitHub App.

#### Response Example
{
  "redirectUrl": "https://github.com/apps/your-app/installations/new"
}

### Error Handling
- **401 Unauthorized** - Missing or invalid authentication.
- **403 Forbidden** - Insufficient permissions.
- **404 Not Found** - Organization not found.
- **500 Internal Server Error** - Unexpected server error.
```

--------------------------------

### GET /v1/install-config

Source: https://openworklabs.com/docs/api-reference/organizations/resolve-install-link-configuration

Resolves the install-link configuration for a given token. Returns organization setup details and a desktop connection handoff.

```APIDOC
## GET /v1/install-config

### Description
Returns organization setup details and a fresh desktop connection handoff for a valid install link token.

### Method
GET

### Endpoint
/v1/install-config

### Parameters
#### Query Parameters
- **token** (string) - Required - The install-link token. Must match pattern ^[A-Za-z0-9_-]{8,}$ and have max length 255.

### Response
#### Success Response (200)
- **appName** (string) - Optional - Default: "OpenWork". Min length 1, max length 64.
- **clientName** (string) - Required - Min length 1.
- **webUrl** (string, uri) - Required - The web URL.
- **apiUrl** (string, uri) - Required - The API URL.
- **requireSignin** (boolean) - Required - Whether sign-in is required.
- **logoUrl** (string, uri or null) - Required - The logo URL.
- **iconUrl** (string, uri or null) - Optional - Default: null.
- **connectUrl** (string) - Required - Min length 1.
- **connectExpiresAt** (string, date-time) - Required - The connection expiry timestamp.
- **activationUrl** (string, uri) - Required - The activation URL.
- **activationExpiresAt** (string, date-time) - Required - The activation expiry timestamp.
- **desktopVersion** (string) - Required - Min length 1.
- **distribution** (string) - Required - Enum: "cloud", "enterprise".

#### Response Example
{
  "appName": "OpenWork",
  "clientName": "string",
  "webUrl": "https://example.com",
  "apiUrl": "https://api.example.com",
  "requireSignin": true,
  "logoUrl": "https://example.com/logo.png",
  "iconUrl": null,
  "connectUrl": "https://example.com/connect",
  "connectExpiresAt": "2025-01-01T00:00:00Z",
  "activationUrl": "https://example.com/activate",
  "activationExpiresAt": "2025-01-01T00:00:00Z",
  "desktopVersion": "1.0.0",
  "distribution": "cloud"
}

#### Error Responses
- **400** - The install-link token was invalid. Response schema: InvalidRequestError.
- **404** - The install link was missing, expired, or revoked. Response schema: InstallLinkNotFoundError.
- **429** - Too many install-link attempts. Response schema: RateLimitedError.

### Security
No authentication required.
```

--------------------------------

### Create private first administrator with docker-compose.eval.yml

Source: https://openworklabs.com/docs/self-host/evaluate-with-docker-compose

Creates a .env file with a random auth secret and DB encryption key, disables public signup, sets the owner email and a one-time setup code, then starts the Compose stack. Run before the first `up` because /setup is only available while the database has no user.

```bash
umask 077
printf 'OPENWORK_AUTH_SECRET=%s\nOPENWORK_DB_ENCRYPTION_KEY=%s\n' \
  "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
printf 'OPENWORK_ALLOW_SIGNUP=false\nOPENWORK_OWNER_EMAILS=%s\nOPENWORK_SETUP_CODE=%s\n' \
  'admin@example.com' "$(openssl rand -hex 16)" >> .env
docker compose -f docker-compose.eval.yml up -d --wait
```

--------------------------------

### GET /v1/install/{platform}

Source: https://openworklabs.com/docs/api-reference/organizations/download-managed-openwork-desktop

Retrieves the managed OpenWork desktop installer for a given platform. The response redirects hosted Cloud deployments to the sign-in-required Cloud app and private single-org deployments to the activation-required Enterprise app.

```APIDOC
## [GET] /v1/install/{platform}

### Description
Retrieves the managed OpenWork desktop installer for a given platform. The endpoint redirects hosted Cloud deployments to the sign-in-required Cloud app and private single-org deployments to the activation-required Enterprise app.

### Method
GET

### Endpoint
/v1/install/{platform}

### Parameters
#### Path Parameters
- **platform** (string) - Required - The target platform identifier for the desktop application.

### Response
#### Success Response (200)
- **installation link** (URL) - The download link or redirect URL for the managed OpenWork desktop.

#### Response Example
The response is a redirect to the appropriate Cloud or Enterprise application based on the platform and organization type.
```

--------------------------------

### OpenWork setup page URL

Source: https://openworklabs.com/docs/self-host/deploy-to-your-cloud/first-administrator

The dedicated setup page for private bootstrap is available at this URL on the Den web hostname. Releases without /setup do not support the private bootstrap flow.

```text
https://<your-den-web-host>/setup
```

--------------------------------

### OpenAPI spec for POST /v1/connectors/github/install/start

Source: https://openworklabs.com/docs/api-reference/github/start-github-install

The OpenAPI specification for the endpoint that starts the GitHub App installation flow. It outlines the server URL, authentication schemes, and the full API description. This document is generated as OpenAPI 3.1.0.

```yaml
openapi: 3.1.0
info:
  title: Den API
  description: >-
    OpenAPI spec for the Den control plane API.


    Authentication:

    - Use `Authorization: Bearer <session-token>` for user-authenticated routes
    that require a Den session.

    - Use `x-api-key: <den-api-key>` for organization API-key calls. API keys
    resolve to the issuing user and the organization member they were scoped to
    when created, so they can call ordinary user and organization routes without
    a separate signed-in session.
      Example: `curl https://api.openworklabs.com/v1/me -H "x-api-key: den_..."`.
    - Session-only flows still require a signed-in user session, including
    organization creation, invitation acceptance, active-organization switching,
    and MCP token minting.

    - Public routes like health and documentation do not require authentication.

    Swagger tip: use the security schemes in the Authorize dialog to set either
    `bearerAuth` or `denApiKey` before trying protected endpoints.
  version: 0.18.46
  contact:
    name: OpenWork
    url: https://openworklabs.com
    email: team@openworklabs.com
  license:
    name: OpenWork Enterprise Edition License
    url: https://github.com/different-ai/openwork/blob/dev/ee/LICENSE
servers:
  - url: https://api.openworklabs.com
security:
  - bearerAuth: []
  - denApiKey: []
tags:
  - name: System
    description: >-
      Service health, readiness, API documentation, and desktop version
      metadata.
  - name: Authentication
    description: >-
      Sign-in discovery, administrator bootstrap, OAuth provider connections,
      and MCP token minting.
  - name: OAuth
    description: >-
      OAuth 2.0 / OpenID Connect authorization-server and protected-resource
      metadata and dynamic client registration (RFC 8414, RFC 9728, RFC 7591),
      used by MCP clients.
  - name: SCIM
    description: >-
      SCIM 2.0 provisioning endpoints for identity providers (RFC 7644) and the
      organization SCIM connector management routes.
  - name: SSO
    description: Organization single sign-on connector management routes.
  - name: Bootstrap
    description: Agent-first provisional workspace setup routes.
  - name: Users
    description: Current user and membership routes.
  - name: Organizations
    description: Organization creation, context, brand assets, and install links.
  - name: Invitations
    description: Invitation preview, acceptance, creation, and cancellation routes.
  - name: Members
    description: Organization member management routes.
  - name: Roles
    description: Organization custom role management routes.
  - name: Teams
    description: Organization team management routes.
  - name: API Keys
    description: Organization API key management routes.
  - name: Desktop Policies
    description: Desktop app policies applied to the organization, members, or teams.
  - name: LLM Providers
    description: Organization LLM provider catalog, configuration, and access routes.
  - name: Inference
    description: Organization inference settings.
  - name: Inference Providers
    description: >-
      Organization inference Gateway providers, model groups, credential sets,
      access grants, member connections, and usage.
  - name: Cloud
    description: Organization Cloud instance lifecycle and browser gateway resolution.
  - name: Workers
    description: Worker lifecycle, billing, and runtime routes.
  - name: Worker Runtime
    description: Worker runtime inspection and upgrade routes.
  - name: Worker Activity
    description: Worker heartbeat and activity reporting routes.
  - name: Automations
    description: Scheduled Automations, their runs, and desktop runner presence.
  - name: Workflows
    description: Saved Workflows (Code Mode scripts), their versions, snapshots, and views.
  - name: Workflow Runs
    description: Durable Workflow run history.
  - name: Codemode Runs
    description: Generated Artifact views produced by Code Mode runs.
  - name: Apps
    description: >-
      Saved reusable apps built from Workflows and Artifact views, and their
      sharing.
  - name: Config Objects
    description: >-
      Versioned configuration objects (skills, workflows, and other plugin
      content).
  - name: Plugins
    description: Plugin packages, access grants, and imports.
  - name: Marketplaces
    description: Marketplaces that distribute plugins to members and teams.
  - name: Resources
    description: >-
      Aggregated snapshot of the resources and marketplace capabilities
      available to the caller.

```

--------------------------------

### Start Gemini CLI

Source: https://openworklabs.com/docs/model-context-protocol/gemini-cli

Command to start the Gemini CLI.

```sh
gemini
```

--------------------------------

### POST /v1/orgs/{organizationId}/install-links

Source: https://openworklabs.com/docs/api-reference/organizations/create-organization-install-link

Creates a new install link for the specified organization. The request body can optionally request rotation of existing links. Returns a token and the install page URL.

```APIDOC
## POST /v1/orgs/{organizationId}/install-links

### Description
Mints a shareable OpenWork desktop install link for a signed-in organization member. Older active links remain valid unless an owner or admin explicitly requests rotation.

### Method
POST

### Endpoint
/v1/orgs/{organizationId}/install-links

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique identifier of the organization.

#### Request Body
- **rotate** (boolean) - Optional - Default: false. If true, rotates existing install links. Only workspace owners and admins can rotate links.

### Request Example
{
  "rotate": false
}

### Response
#### Success Response (200)
- **token** (string) - The install link token.
- **installPageUrl** (string, uri) - The URL to the install page.

#### Response Example
{
  "token": "string",
  "installPageUrl": "string"
}

#### Error Responses
- **400** - The install-link request was invalid. Returns InvalidRequestError.
- **401** - The caller must be signed in to create install links. Returns UnauthorizedError.
- **403** - The organization needs the installLinks capability enabled, and only workspace owners and admins can rotate existing links. Returns ForbiddenError or CapabilityDisabledError.
- **404** - The organization could not be found. Returns NotFoundError.
- **429** - The member has created too many install links. Returns RateLimitedError.

### Security
- bearerAuth
- denApiKey
```

--------------------------------

### POST /v1/orgs/{organizationId}/install-links

Source: https://openworklabs.com/docs/api-reference/organizations/create-organization-install-link

Creates a shareable OpenWork desktop install link for a signed-in organization member. The link is minted for the specified organization and can be used to install the desktop app.

```APIDOC
## POST /v1/orgs/{organizationId}/install-links

### Description
Creates a shareable OpenWork desktop install link for a signed-in organization member. Older active links remain valid unless an owner or admin explicitly requests rotation.

### Method
POST

### Endpoint
/v1/orgs/{organizationId}/install-links

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique identifier of the organization.

### Authentication
- **bearerAuth** - Required - Use `Authorization: Bearer <session-token>` for user-authenticated routes.
- **denApiKey** - Required - Use `x-api-key: <den-api-key>` for organization API-key calls.

### Request Example
No request body is required.

### Response
#### Success Response (200)
- **installLink** (string) - The generated install link.

#### Response Example
{
  "installLink": "https://openworklabs.com/install/..."
}
```

--------------------------------

### POST /v1/bootstrap/workspace

Source: https://openworklabs.com/docs/api-reference/bootstrap/create-a-provisional-workspace-for-agent-first-setup

Creates a provisional workspace, setup member, starter skill, and short-lived claim links without requiring an email account first. The request body must include a workspaceName, and the response provides the organization and setup details.

```APIDOC
## POST /v1/bootstrap/workspace

### Description
Creates a provisional workspace, setup member, starter skill, and short-lived claim links without requiring an email account first.

### Method
POST

### Endpoint
/v1/bootstrap/workspace

### Parameters
#### Request Body
- **workspaceName** (string) - Required - Minimum length 2, maximum length 120.
- **skillName** (string) - Optional - Default: "First OpenWork Skill". Minimum length 1, maximum length 120.
- **devicePublicKey** (string) - Optional - Minimum length 16, maximum length 4096.
- **claimRoles** (array of string) - Optional - Default: ["owner"]. Minimum items 1, maximum items 3. Allowed values: owner, admin, member.
- **ownerEmail** (string) - Optional - Maximum length 255, format email, pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
- **teammateEmails** (array of string) - Optional - Maximum items 10. Each item: maximum length 255, format email, pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

### Request Example
{
  "workspaceName": "My Workspace",
  "skillName": "First OpenWork Skill",
  "devicePublicKey": "...",
  "claimRoles": ["owner"],
  "ownerEmail": "owner@example.com",
  "teammateEmails": ["teammate@example.com"]
}

### Response
#### Success Response (200)
- **ok** (boolean) - Always true.
- **organization** (object) - Contains id, name, slug, status.
  - **id** (string) - Den TypeID with 'org_' prefix and a 26-character base32 suffix. Length exactly 30.
  - **name** (string) - Workspace name.
  - **slug** (string) - Workspace slug.
  - **status** (string) - Always "provisional".
- **setup** (object) - Contains id and expiresAt.
  - **id** (string) - Den TypeID with 'wbt_' prefix and a 26-character base32 suffix. Length exactly 30.
  - **expiresAt** (string) - Date-time format.

#### Response Example
{
  "ok": true,
  "organization": {
    "id": "org_...",
    "name": "My Workspace",
    "slug": "my-workspace",
    "status": "provisional"
  },
  "setup": {
    "id": "wbt_...",
    "expiresAt": "2025-01-01T00:00:00Z"
  }
}
```

--------------------------------

### Minimum hosted desktop allowlist hosts

Source: https://openworklabs.com/docs/start-here/outbound-network-access

Allow TCP 443 to these hosts for a practical OpenWork Cloud desktop install. Common misses include GitHub release downloads redirecting away from github.com, so allow release-assets.githubusercontent.com and objects.githubusercontent.com for older clients and rollback paths. registry.npmjs.org is used when packaged desktop builds start npx -y openwork-ui-mcp; if blocked, the desktop can still open but UI-control MCP is unavailable. models.openworklabs.com is the default OpenCode model catalog; set OPENCODE_MODELS_URL to an approved internal mirror if the public catalog is blocked.

```text
app.openworklabs.com
api.app.openworklabs.com
github.com
release-assets.githubusercontent.com
objects.githubusercontent.com
registry.npmjs.org
models.openworklabs.com
```

--------------------------------

### desktop-bootstrap.json example

Source: https://openworklabs.com/docs/start-here/enterprise-desktop-deployment

JSON configuration file for enterprise desktop deployment. Place it at the canonical path for your OS (e.g., %LOCALAPPDATA%\openwork\desktop-bootstrap.json on Windows, $XDG_CONFIG_HOME/openwork/desktop-bootstrap.json on macOS/Linux). The baseUrl is required; apiBaseUrl is optional. requireSignin is required but enterprise builds enforce sign-in regardless. writtenAt is required and the newest timestamp wins when multiple files exist.

```json
{
  "baseUrl": "https://openwork.example.com",
  "apiBaseUrl": "https://openwork.example.com/api/den",
  "requireSignin": true,
  "brandAppName": "Example Corp OpenWork",
  "writtenAt": "2026-08-20T12:00:00.000Z"
}
```

--------------------------------

### GET /v1/sso

Source: https://openworklabs.com/docs/api-reference/sso/get-organization-sso-connection

Retrieves the current organization's SSO connection and setup URLs. Requires bearer authentication and appropriate permissions.

```APIDOC
## GET /v1/sso

### Description
Returns the current organization SSO connection and setup URLs.

### Method
GET

### Endpoint
/v1/sso

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **connection** (object or null) - The organization SSO connection, or null if not configured.
- **domainVerificationToken** (string or null) - Token used to verify domain ownership.

#### Response Example
{
  "connection": {
    "id": "string",
    "providerId": "string",
    "kind": "oidc",
    "issuer": "https://example.com",
    "domain": "example.com",
    "status": "enabled",
    "testStatus": "succeeded",
    "testExpiresAt": "2024-01-01T00:00:00Z"
  },
  "domainVerificationToken": "string"
}

#### Error Responses
- **400** - Invalid request. Response schema: SsoInvalidRequestError
- **401** - Unauthorized. Response schema: SsoUnauthorizedError
- **403** - Only workspace owners and admins can read SSO. Response schema: SsoForbiddenError
- **404** - Organization not found. Response schema: SsoOrganizationNotFoundError

### Security
- bearerAuth: []
```

--------------------------------

### GET /v1/me/install-config

Source: https://openworklabs.com/docs/api-reference/users/get-current-users-install-configuration

Returns desktop branding, distribution, and approved version for the signed-in member's active organization. Requires authentication.

```APIDOC
## GET /v1/me/install-config

### Description
Returns desktop branding, distribution, and approved version for the signed-in member's active organization.

### Method
GET

### Endpoint
/v1/me/install-config

### Parameters
None

### Request Example
No request body required.

### Response
#### Success Response (200)
- **appName** (string) - Optional - Default: "OpenWork" - The application name.
- **clientName** (string) - Required - The client name.
- **webUrl** (string, uri) - Required - The web URL.
- **apiUrl** (string, uri) - Required - The API URL.
- **requireSignin** (boolean) - Required - Whether sign-in is required.
- **logoUrl** (string, uri or null) - Required - The logo URL.
- **iconUrl** (string, uri or null) - Optional - Default: null - The icon URL.
- **desktopVersion** (string) - Required - The desktop version.
- **distribution** (string) - Required - Enum: "cloud", "enterprise" - The distribution type.

#### Response Example
{
  "appName": "OpenWork",
  "clientName": "string",
  "webUrl": "string",
  "apiUrl": "string",
  "requireSignin": true,
  "logoUrl": "string",
  "iconUrl": null,
  "desktopVersion": "string",
  "distribution": "cloud"
}

#### Error Responses
- **401 Unauthorized**: The caller must be signed in to load install configuration. Response schema: UnauthorizedError (error: "unauthorized").
- **404 Not Found**: The caller has no active organization membership. Response schema: NotFoundError (error, message).

### Security
- bearerAuth: Session token passed as `Authorization: Bearer <session-token>`.
- denApiKey: Organization API key passed as the `x-api-key` header.
```

--------------------------------

### GET /v1/admin/organizations/{organizationId}/capabilities

Source: https://openworklabs.com/docs/api-reference/admin/get-an-organizations-capability-overrides

Returns the admin-visible capability flags (install links, MCP connections) for the organization. The caller must be an authenticated admin.

```APIDOC
## GET /v1/admin/organizations/{organizationId}/capabilities

### Description
Returns the admin-visible capability flags (install links, MCP connections) for the organization.

### Method
GET

### Endpoint
/v1/admin/organizations/{organizationId}/capabilities

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique identifier of the organization.

### Response
#### Success Response (200)
- **capabilities** (object) - The capability overrides for the organization.

#### Response Example
{
  "capabilities": {}
}

#### Error Responses
- **400** - The organization id was invalid.
  - **error** (string) - Always "invalid_request".
  - **message** (string) - Error description.
- **401** - The caller must be authenticated.
  - **error** (string) - Always "unauthorized".
- **403** - The authenticated user is not an admin.
  - **error** (string) - One of "forbidden" or "reauth".
  - **reason** (string) - Optional reason.
  - **message** (string) - Optional message.
- **404** - The organization does not exist.
  - **error** (string) - Error code.
  - **message** (string) - Error description.

### Security
- **bearerAuth** - Session token passed as `Authorization: Bearer <session-token>`.
- **denApiKey** - Organization API key passed as the `x-api-key` header.
```

--------------------------------

### GET /v1/admin/organizations/{organizationId}/capabilities

Source: https://openworklabs.com/docs/api-reference/admin/get-an-organizations-capability-overrides

Returns the admin-visible capability flags (install links, MCP connections) for the organization. This endpoint is part of the Den API and requires authentication.

```APIDOC
## GET /v1/admin/organizations/{organizationId}/capabilities

### Description
Returns the admin-visible capability flags (install links, MCP connections) for the organization.

### Method
GET

### Endpoint
/v1/admin/organizations/{organizationId}/capabilities

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique identifier of the organization.

### Authentication
- **bearerAuth** - Use `Authorization: Bearer <session-token>` for user-authenticated routes.
- **denApiKey** - Use `x-api-key: <den-api-key>` for organization API-key calls.

### Response
#### Success Response (200)
Returns the admin-visible capability flags for the organization.

#### Response Example
(No response example provided in the source.)
```

--------------------------------

### POST /v1/connectors/github/setup

Source: https://openworklabs.com/docs/api-reference/github/setup-github-connector

Creates a GitHub connector account, instance, target, and initial mappings in one flow.

```APIDOC
## POST /v1/connectors/github/setup

### Description
Creates a GitHub connector account, instance, target, and initial mappings in one flow.

### Method
POST

### Endpoint
/v1/connectors/github/setup

### Parameters
#### Request Body
- **installationId** (integer) - Required - GitHub App installation ID. Must be greater than 0 and less than or equal to 9007199254740991.
- **connectorAccountId** (string, typeid) - Optional - Den TypeID with 'cac_' prefix and a 26-character base32 suffix. Must be exactly 30 characters.
- **connectorInstanceName** (string) - Required - Name of the connector instance. Must be between 1 and 255 characters.
- **repositoryId** (integer) - Required - GitHub repository ID. Must be greater than 0 and less than or equal to 9007199254740991.
- **repositoryFullName** (string) - Required - Full name of the repository (e.g., owner/repo). Must be between 1 and 255 characters.
- **branch** (string) - Required - Branch name. Must be between 1 and 255 characters.
- **ref** (string) - Required - Git reference. Must be between 1 and 255 characters.
- **mappings** (array) - Optional - Array of mapping objects. Maximum 100 items.
  - **mappingKind** (string) - Required - Enum: path, api, custom.
  - **selector** (string) - Required - Selector string. Must be between 1 and 255 characters.
  - **objectType** (string) - Required - Enum: skill, agent, command, tool, mcp, hook, context, custom, script, workflow, app.
  - **pluginId** (string or null) - Optional - Den TypeID with 'plg_' prefix and a 26-character base32 suffix. Must be exactly 30 characters.
  - **autoAddToPlugin** (boolean) - Optional - Default: false.
  - **config** (object) - Optional - Additional configuration properties.

### Request Example
```json
{
  "installationId": 123456,
  "connectorAccountId": "cac_abcdefghijklmnopqrstuvwxyz123456",
  "connectorInstanceName": "my-github-connector",
  "repositoryId": 987654,
  "repositoryFullName": "octocat/Hello-World",
  "branch": "main",
  "ref": "refs/heads/main",
  "mappings": [
    {
      "mappingKind": "path",
      "selector": "src/skills",
      "objectType": "skill",
      "pluginId": "plg_abcdefghijklmnopqrstuvwxyz123456",
      "autoAddToPlugin": true,
      "config": {}
    }
  ]
}
```

### Response
#### Success Response (201)
- **201** - GitHub connector setup created successfully.
- Response body schema: PluginArchGithubSetupResponse (referenced in components).

#### Response Example
```json
{
  "id": "cac_abcdefghijklmnopqrstuvwxyz123456",
  "status": "created"
}
```

#### Error Responses
- **400** - Bad request. The request body is invalid or missing required fields.
```

--------------------------------

### GET /v1/marketplaces/{marketplaceId}/resolved

Source: https://openworklabs.com/docs/api-reference/marketplaces/get-resolved-marketplace-plugin-readiness

Retrieves marketplace details including plugins, derived source information, and each plugin's cloud readiness or required setup state.

```APIDOC
## GET /v1/marketplaces/{marketplaceId}/resolved

### Description
Returns marketplace detail with plugins, derived source info, and each plugin's cloud readiness or required setup state.

### Method
GET

### Endpoint
/v1/marketplaces/{marketplaceId}/resolved

### Parameters
#### Path Parameters
- **marketplaceId** (string) - Required - Den TypeID with 'mkt_' prefix and a 26-character base32 suffix.

### Response
#### Success Response (200)
- **ok** (boolean) - Always true.
- **item** (object) - Contains marketplace details and plugin readiness information.

#### Response Example
```json
{
  "ok": true,
  "item": {
    "marketplace": {
      "externalKey": null,
      "id": "mkt_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "organizationId": "org_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "name": "string",
      "description": null,
      "logoUrl": null,
      "status": "active",
      "createdByOrgMembershipId": "om_xxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "createdAt": "2023-01-01T00:00:00Z"
    }
  }
}
```

#### Error Responses
- **400** - The marketplace path parameters were invalid.
- **401** - The caller must be signed in to view marketplaces.
- **404** - The marketplace could not be found.
```

--------------------------------

### POST /v1/connectors/github/install/complete

Source: https://openworklabs.com/docs/api-reference/github/complete-github-install

Completes a GitHub App installation for the current organization and returns visible repositories.

```APIDOC
## POST /v1/connectors/github/install/complete

### Description
Completes a GitHub App installation for the current organization and returns visible repositories.

### Method
POST

### Endpoint
/v1/connectors/github/install/complete

### Authentication
- bearerAuth (Required) - Use `Authorization: Bearer <session-token>` for user-authenticated routes.
- denApiKey (Required) - Use `x-api-key: <den-api-key>` for organization API-key calls.

### Response
#### Success Response (200)
Returns the visible repositories for the organization after completing the GitHub App installation.

```

--------------------------------

### POST /v1/connectors/github/install/complete

Source: https://openworklabs.com/docs/api-reference/github/complete-github-install

Completes a GitHub App installation for the current organization and returns visible repositories. Requires installationId and state in the request body.

```APIDOC
## [POST] /v1/connectors/github/install/complete

### Description
Completes a GitHub App installation for the current organization and returns visible repositories.

### Method
POST

### Endpoint
/v1/connectors/github/install/complete

### Parameters
#### Request Body
- **installationId** (integer) - Required - The GitHub installation ID. Must be greater than 0 and less than or equal to 9007199254740991.
- **state** (string) - Required - The state token for the installation. Must be between 1 and 4096 characters.

### Request Example
{
  "installationId": 123456,
  "state": "state-token"
}

### Response
#### Success Response (200)
- **ok** (boolean) - Always true.
- **item** (object) - Contains the connector account and repositories.
  - **connectorAccount** (object) - The connector account details.
  - **repositories** (array) - List of visible GitHub repositories.

#### Response Example
{
  "ok": true,
  "item": {
    "connectorAccount": {
      "id": "cac_...",
      "organizationId": "org_..."
    },
    "repositories": []
  }
}

### Error Responses
#### 400 Bad Request
- **error** (string) - Always "invalid_request".
- **details** (array) - List of validation errors.
  - **message** (string) - Error message.
  - **path** (array) - Path to the invalid field.
- **capability** (string) - Optional capability name.

#### 401 Unauthorized
- **error** (string) - Always "unauthorized".

#### 403 Forbidden
- **error** (string) - Either "forbidden" or "reauth".
- **reason** (string) - Optional reason.
- **message** (string) - Optional message.

### Security
- bearerAuth
- denApiKey
```

--------------------------------

### GET /v1/cloud/gateway/resolve

Source: https://openworklabs.com/docs/api-reference/cloud/resolve-the-callers-cloud-instance-for-the-browser-gateway

Starts or wakes the caller's own OpenWork Cloud browser instance when needed and returns the collaborator token only to the trusted gateway. Requires bearer authentication or an API key.

```APIDOC
## GET /v1/cloud/gateway/resolve

### Description
Starts or wakes the caller's own OpenWork Cloud browser instance when needed and returns the collaborator token only to the trusted gateway.

### Method
GET

### Endpoint
/v1/cloud/gateway/resolve

### Authentication
- bearerAuth (required)
- denApiKey (required)

### Response
#### Success Response (200)
- **status** (string) - Enum: provisioning, waking, ready, failed
- **url** (string or null) - URI of the Cloud instance
- **clientToken** (string or null) - Client token for the gateway
- **hostToken** (string or null) - Host token for the gateway
- **expiresAt** (string or null) - Date-time when the tokens expire
- **failure** (object) - Failure details if status is failed
  - **code** (string) - Failure code
  - **stage** (string) - Enum: provisioning, recovery, runtime
  - **reference** (string) - Reference identifier
  - **occurredAt** (string) - Date-time when the failure occurred
- **providerSync** (object) - Provider sync status
  - **status** (string) - Const: degraded
  - **reason** (string) - Const: unsupported

#### Response Example
{
  "status": "ready",
  "url": "https://example.com/cloud",
  "clientToken": "token",
  "hostToken": "token",
  "expiresAt": "2023-01-01T00:00:00Z",
  "failure": null,
  "providerSync": {
    "status": "degraded",
    "reason": "unsupported"
  }
}

#### Error Responses
- **401** - The caller must be signed in to open Cloud.
  - **error** (string) - Const: unauthorized
- **403** - OpenWork Web access is not active for the organization.
  - **error** (string) - Const: openwork_web_access_required
- **404** - Cloud is not available for this organization or gateway.
  - **error** (string) - Const: not_found

```

--------------------------------

### GET /v1/cloud/instance

Source: https://openworklabs.com/docs/api-reference/cloud/get-the-active-organizations-cloud-instance

Starts the active organization's OpenWork Cloud browser instance when needed and returns its browser URL once ready. This endpoint is part of the Cloud tag and requires authentication.

```APIDOC
## GET /v1/cloud/instance

### Description
Starts the active organization's OpenWork Cloud browser instance when needed and returns its browser URL once ready.

### Method
GET

### Endpoint
/v1/cloud/instance

### Authentication
- **bearerAuth** - Required - Use `Authorization: Bearer <session-token>` for user-authenticated routes.
- **denApiKey** - Required - Use `x-api-key: <den-api-key>` for organization API-key calls.

### Response
#### Success Response (200)
Returns the browser URL of the Cloud instance once it is ready.

#### Response Example
{
  "browserUrl": "https://..."
}
```

--------------------------------

### GET /v1/cloud/instance

Source: https://openworklabs.com/docs/api-reference/cloud/get-the-active-organizations-cloud-instance

Starts the active organization's OpenWork Cloud browser instance when needed and returns its browser URL once ready. Requires authentication via bearer token or API key.

```APIDOC
## GET /v1/cloud/instance

### Description
Starts the active organization's OpenWork Cloud browser instance when needed and returns its browser URL once ready.

### Method
GET

### Endpoint
/v1/cloud/instance

### Parameters
No parameters are documented for this endpoint.

### Request Example
No request body is required.

### Response
#### Success Response (200)
- **status** (string) - The status of the Cloud instance. Possible values: provisioning, waking, ready, failed.
- **url** (string or null) - The browser URL of the Cloud instance.
- **imageVersion** (string or null) - The image version of the Cloud instance.
- **instanceName** (string or null) - The name of the Cloud instance.
- **latestVersion** (string or null) - The latest available version.
- **failure** (object or null) - Failure details if the instance failed. Contains code, stage, reference, and occurredAt.

#### Response Example
{
  "status": "ready",
  "url": "https://example.com",
  "imageVersion": "1.0.0",
  "instanceName": "my-instance",
  "latestVersion": "1.0.1",
  "failure": null
}

#### Error Responses
- **401** - The caller must be signed in to open Cloud. Response body: { "error": "unauthorized" }
- **403** - OpenWork Web access is not active for the organization. Response body: { "error": "openwork_web_access_required", "message": "..." }
- **404** - Cloud is not available for this organization. Response body: { "error": "...", "message": "..." }

### Authentication
- **bearerAuth** - Session token passed as `Authorization: Bearer <session-token>`.
- **denApiKey** - Organization API key passed as the `x-api-key` header. The raw key is the header value; do not prefix it with `Bearer`.
```

--------------------------------

### Create the MCP server (server.ts)

Source: https://openworklabs.com/docs/cloud/share-with-your-team/dashboards

Sets up an MCP server with a resource for the view and a tool 'get_budget' that returns budget data. Uses Express and StreamableHTTPServerTransport. Requires installing @modelcontextprotocol/sdk, @modelcontextprotocol/ext-apps, and express.

```TypeScript
import express from "express";
import { readFile } from "node:fs/promises";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";

const server = new McpServer({ name: "team-budget", version: "1.0.0" });
const html = await readFile(new URL("./view.html", import.meta.url), "utf8");

registerAppResource(
  server,
  "budget-view",
  "ui://team-budget/view.html",
  { mimeType: RESOURCE_MIME_TYPE },
  async () => ({
    contents: [{
      uri: "ui://team-budget/view.html",
      mimeType: RESOURCE_MIME_TYPE,
      text: html,
    }],
  }),
);

registerAppTool(
  server,
  "get_budget",
  {
    title: "Team budget",
    description: "Current budget allocation by team",
    inputSchema: {},
    annotations: { readOnlyHint: true },
    _meta: { ui: { resourceUri: "ui://team-budget/view.html" } },
  },
  async () => {
    const data = { teams: [
      { name: "Engineering", percent: 42 },
      { name: "Sales", percent: 33 },
      { name: "Operations", percent: 25 },
    ] };
    return {
      content: [{ type: "text", text: JSON.stringify(data) }],
      structuredContent: data,
    };
  },
);

const app = express();
app.use(express.json());
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);
app.all("/mcp", (req, res) => transport.handleRequest(req, res, req.body));
app.listen(3000);
```

--------------------------------

### Helm values for public web and API origins

Source: https://openworklabs.com/docs/start-here/github-connector-helm

Set the same public hosts used in the Helm chart. The GitHub App needs the Homepage URL and Setup URL from these origins to complete installation.

```yaml
config:
  public:
    webOrigin: "https://openwork.example.com"
    apiOrigin: "https://api.openwork.example.com"
```

--------------------------------

### GET /v1/me/install/{platform}

Source: https://openworklabs.com/docs/api-reference/users/download-current-users-managed-openwork-desktop

Downloads the Cloud or Enterprise desktop artifact approved for the signed-in member's active organization. The platform path parameter specifies the target desktop platform.

```APIDOC
## GET /v1/me/install/{platform}

### Description
Downloads the Cloud or Enterprise artifact approved for the signed-in member's active organization.

### Method
GET

### Endpoint
/v1/me/install/{platform}

### Parameters
#### Path Parameters
- **platform** (string) - Required - The desktop platform identifier.

### Response
#### Success Response (200)
- Returns the mounted desktop artifact as text/plain.

#### Redirect (302)
- Den redirected the browser to the signed desktop asset for this deployment.

#### Error Responses
- **400** - The desktop platform was invalid. Returns an InvalidRequestError.
- **401** - The caller must be signed in to download the desktop app. Returns an UnauthorizedError.
- **404** - The caller has no active organization membership. Returns a NotFoundError.
- **429** - Too many installer download attempts. Returns a RateLimitedError.

### Security
- bearerAuth: Session token passed as `Authorization: Bearer <session-token>`.
- denApiKey: Organization API key passed as the `x-api-key` header.

```

--------------------------------

### GET /v1/me/install-config

Source: https://openworklabs.com/docs/api-reference/users/get-current-users-install-configuration

Retrieves the desktop branding, distribution, and approved version for the active organization of the signed-in member. This endpoint requires authentication via bearer token or API key.

```APIDOC
## [GET] /v1/me/install-config

### Description
Returns desktop branding, distribution, and approved version for the signed-in member's active organization.

### Method
GET

### Endpoint
https://api.openworklabs.com/v1/me/install-config

### Authentication
- **bearerAuth** - Optional - Bearer token for user-signed-in sessions. Format: `Authorization: Bearer <session-token>`
- **denApiKey** - Optional - Organization API key. Format: `x-api-key: <den-api-key>`

### Parameters
No parameters are explicitly documented for this endpoint.

### Response
#### Success Response (200)
- **branding** (object) - Desktop branding details
- **distribution** (object) - Distribution information
- **approvedVersion** (string) - Approved version for the active organization


```

--------------------------------

### GET /v1/me/install/{platform}

Source: https://openworklabs.com/docs/api-reference/users/download-current-users-managed-openwork-desktop

Downloads the Cloud or Enterprise artifact approved for the signed-in member's active organization. The platform path parameter specifies the target operating system.

```APIDOC
## GET /v1/me/install/{platform}

### Description
Downloads the Cloud or Enterprise artifact approved for the signed-in member's active organization.

### Method
GET

### Endpoint
`https://api.openworklabs.com/v1/me/install/{platform}`

### Parameters
#### Path Parameters
- **platform** (string) - Required - The target platform for the desktop artifact (e.g., windows, mac, linux).

### Authentication
- `Authorization: Bearer <session-token>` for user-authenticated routes.
- `x-api-key: <den-api-key>` for organization API-key calls.

### Response
#### Success Response (200)
Returns the binary artifact for the specified platform.

#### Response Example
Binary file download.

```