# Workspace API

The Workspace API manages organizations, projects, project API keys, members, Gateway settings, and
integrations. Most routes are project-qualified because they operate on a specific project or
organization.

Base URL:

```text
https://api.provon.dev/v1
```

## Authentication

Workspace routes accept two credential types:

- **Project API key** — `Authorization: Bearer <PROVON_API_KEY>`. The key selects the project for
  public `/v1/*` routes. For project-qualified routes, the key must have access to the requested
  `:projectId`.
- **Signed-in Workbench session** — AuthJS session cookie. Used for `/v1/projects/:projectId/*`
  routes when the calling user has the required project permission.

The pages below call out which credential type each route supports. Routes that only make sense in a
browser sign-in flow (registration, password reset, billing checkout, connector OAuth callbacks) are
not documented here.

Required capabilities and permissions:

| Operation               | API key capability | Workbench permission |
| ----------------------- | ------------------ | -------------------- |
| Read organizations      | `workspace:read`   | n/a (user-scoped)    |
| Create organizations    | `workspace:write`  | n/a (user-scoped)    |
| Read projects           | `workspace:read`   | `project:read`       |
| Create/update projects  | `workspace:write`  | `project:update`     |
| Manage project API keys | `workspace:write`  | `project:update`     |
| Manage Gateway settings | `workspace:write`  | `project:update`     |
| Manage integrations     | `workspace:write`  | `project:update`     |
| Manage project members  | `workspace:write`  | `project:update`     |

## Organizations

| Method   | Path                                                          | Purpose                         |
| -------- | ------------------------------------------------------------- | ------------------------------- |
| `GET`    | `/v1/organizations`                                           | List actor organizations        |
| `POST`   | `/v1/organizations`                                           | Create an organization          |
| `GET`    | `/v1/organizations/:organizationId`                           | Read one organization           |
| `PATCH`  | `/v1/organizations/:organizationId`                           | Update organization name/region |
| `POST`   | `/v1/organizations/:organizationId/invitations`               | Invite a member                 |
| `DELETE` | `/v1/organizations/:organizationId/invitations/:invitationId` | Revoke an invitation            |
| `POST`   | `/v1/organization-invitations/:token/accept`                  | Accept an invitation (session)  |
| `PATCH`  | `/v1/organizations/:organizationId/members/:memberId`         | Update member role              |
| `DELETE` | `/v1/organizations/:organizationId/members/:memberId`         | Remove member                   |

Create an organization:

```bash
curl -X POST "$PROVON_API_URL/organizations" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme AI"}'
```

Invite a member:

```bash
curl -X POST "$PROVON_API_URL/organizations/$ORG_ID/invitations" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "colleague@example.com", "role": "MEMBER"}'
```

## Projects

| Method   | Path                                      | Purpose              |
| -------- | ----------------------------------------- | -------------------- |
| `GET`    | `/v1/projects`                            | List projects        |
| `POST`   | `/v1/projects`                            | Create a project     |
| `GET`    | `/v1/projects/:projectId`                 | Read one project     |
| `PATCH`  | `/v1/projects/:projectId`                 | Update project       |
| `DELETE` | `/v1/projects/:projectId`                 | Delete project       |
| `PUT`    | `/v1/projects/:projectId/members/:userId` | Set member role      |
| `DELETE` | `/v1/projects/:projectId/members/:userId` | Remove member        |
| `GET`    | `/v1/projects/:projectId/setup-status`    | Setup status summary |

Create a project:

```bash
curl -X POST "$PROVON_API_URL/projects" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "org_...", "name": "Production agents"}'
```

## Project API Keys

| Method   | Path                                                               | Purpose                  |
| -------- | ------------------------------------------------------------------ | ------------------------ |
| `GET`    | `/v1/projects/:projectId/api-keys`                                 | List project API keys    |
| `POST`   | `/v1/projects/:projectId/api-keys`                                 | Create a project API key |
| `PATCH`  | `/v1/projects/:projectId/api-keys/:keyId`                          | Update key note          |
| `DELETE` | `/v1/projects/:projectId/api-keys/:keyId`                          | Revoke a key             |
| `POST`   | `/v1/projects/:projectId/api-keys/:keyId/usage-policies`           | Create a usage policy    |
| `PATCH`  | `/v1/projects/:projectId/api-keys/:keyId/usage-policies/:policyId` | Update a usage policy    |
| `DELETE` | `/v1/projects/:projectId/api-keys/:keyId/usage-policies/:policyId` | Delete a usage policy    |

Create a key:

```bash
curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/api-keys" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI ingest key",
    "capabilities": ["telemetry:ingest"]
  }'
```

The response includes the full secret once; store it immediately. Capabilities follow the same
names documented in [API Reference](./index.md).

## Gateway Settings

Project Gateway settings configure provider keys, model policies, auto-router, guardrails, and
observability. These routes are session-backed in the Workbench and may also be available to API-key
callers with `workspace:write` depending on the deployment.

| Method   | Path                                             | Purpose                        |
| -------- | ------------------------------------------------ | ------------------------------ |
| `GET`    | `/v1/projects/:projectId/gateway/settings`       | Read Gateway settings          |
| `PUT`    | `/v1/projects/:projectId/gateway/settings`       | Replace Gateway settings       |
| `DELETE` | `/v1/projects/:projectId/gateway/settings`       | Delete Gateway settings        |
| `POST`   | `/v1/projects/:projectId/gateway/model-policies` | Update model policies          |
| `POST`   | `/v1/projects/:projectId/gateway/auto-router`    | Update auto-router config      |
| `POST`   | `/v1/projects/:projectId/gateway/guardrails`     | Update guardrails              |
| `POST`   | `/v1/projects/:projectId/gateway/observability`  | Update observability config    |
| `POST`   | `/v1/projects/:projectId/gateway/pause`          | Pause Gateway for the project  |
| `POST`   | `/v1/projects/:projectId/gateway/resume`         | Resume Gateway for the project |

For provider key and model-binding management from service clients, see [Gateway API](./gateway.md).

## Integrations

Project integrations connect Findings and notifications to external systems. Configuration is
usually done through the Workbench because some connectors require OAuth flows.

| Method   | Path                                                       | Purpose                      |
| -------- | ---------------------------------------------------------- | ---------------------------- |
| `GET`    | `/v1/projects/:projectId/integrations`                     | List configured connectors   |
| `PUT`    | `/v1/projects/:projectId/integrations/:kind`               | Create or update a connector |
| `DELETE` | `/v1/projects/:projectId/integrations/:kind`               | Delete a connector           |
| `GET`    | `/v1/projects/:projectId/integrations/:kind/authorize`     | Start OAuth authorization    |
| `GET`    | `/v1/integrations/:kind/callback`                          | OAuth callback               |
| `GET`    | `/v1/projects/:projectId/integrations/github/repositories` | List GitHub repositories     |

Supported connector kinds include `github`, `gitlab`, `linear`, `jira`, `slack`, `airtable`,
`notion`, `monday`, and generic notification integrations.

## Account And Workspace Setup

These routes are session-backed and are used by the Workbench during onboarding and account
management.

| Method  | Path                              | Purpose                             |
| ------- | --------------------------------- | ----------------------------------- |
| `GET`   | `/v1/account`                     | Read current account settings       |
| `PATCH` | `/v1/account`                     | Update account settings             |
| `POST`  | `/v1/account/session-revocations` | Revoke all other sessions           |
| `GET`   | `/v1/workspace`                   | Read workspace summary              |
| `GET`   | `/v1/workspace-initialization`    | Get default onboarding organization |
| `PUT`   | `/v1/workspace-initialization`    | Ensure initial workspace            |
| `POST`  | `/v1/workspace/provision`         | Provision first project and API key |

## Errors

Workspace errors use the shared API error envelope:

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "actor cannot create projects in organization",
    "details": {}
  }
}
```

Common status codes:

| Status | Meaning                                       |
| ------ | --------------------------------------------- |
| `400`  | Validation error or missing required field    |
| `401`  | Missing or invalid credential                 |
| `403`  | Credential lacks capability or permission     |
| `404`  | Organization, project, key, or member missing |
| `409`  | Conflict (duplicate slug, active invitation)  |