Workspace Integrations API

Configure external service integrations at workspace or project level. Supports Jira, GitHub, Git, and SMTP.

TIP

Organization-level integrations (shared across all workspaces) are managed via the Organization Integrations API. Configuration resolves in order: Project → Workspace → Organization → Global.

List Integrations

Returns all integration types with their resolved configuration (project → workspace → global fallback).

GET /api/v1/workspaces/{workspace_id}/integrations?project_id={project_id}
Authorization: Bearer <token>

Response 200 OK

[
  {
    "type": "jira",
    "label": "Jira",
    "configured": true,
    "enabled": true,
    "scope": "workspace",
    "config_summary": { "base_url": "https://mycompany.atlassian.net" },
    "has_project_override": false
  },
  {
    "type": "github",
    "label": "GitHub",
    "configured": false,
    "enabled": false,
    "scope": null,
    "config_summary": {},
    "has_project_override": false
  }
]

Get Integration Config

Requires admin role.

GET /api/v1/workspaces/{workspace_id}/integrations/jira?project_id={project_id}
Authorization: Bearer <token>

Upsert Integration Config

Create or update an integration configuration. Use project_id query parameter to set a project-level override.

PUT /api/v1/workspaces/{workspace_id}/integrations/jira
Authorization: Bearer <token>
Content-Type: application/json

{
  "config": {
    "base_url": "https://mycompany.atlassian.net",
    "email": "bot@company.com",
    "api_token": "...",
    "project_key": "PROJ"
  },
  "enabled": true
}

Delete Integration

DELETE /api/v1/workspaces/{workspace_id}/integrations/jira?project_id={project_id}
Authorization: Bearer <token>

Test Connection

Test connectivity for any integration type.

POST /api/v1/workspaces/{workspace_id}/integrations/jira/test
Authorization: Bearer <token>

Supported Types: jira, github, git, smtp

Response 200 OK

{
  "status": "ok",
  "message": "Connected successfully",
  "deployment": "Cloud",
  "user": "bot@company.com"
}

External Tracker Links

List work items linked to external issue trackers (Jira, GitHub Issues, Linear).

GET /api/v1/workspaces/{workspace_id}/integrations/links
Authorization: Bearer <token>

Jira Webhook

Inbound webhook endpoint for Jira change notifications.

POST /api/v1/integrations/jira/webhook
Content-Type: application/json

{ ... Jira webhook payload ... }

Processes issue status changes and syncs them back to Forgexa work items.