Workspace API

Base URL:

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:

Organizations#

Create an organization:

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:

curl -X POST "$PROVON_API_URL/organizations/$ORG_ID/invitations" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "role": "MEMBER"}'

Projects#

Create a project:

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#

Create a key:

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.

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.

For provider key and model-binding management from service clients, see Gateway API.

Integrations#

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

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.

Errors#

Workspace errors use the shared API error envelope:

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

Common status codes: