Organization Integrations API

Configure external service integrations at the organization level. Organization-level integrations serve as defaults for all workspaces within the organization.

Resolution Order: Project → Workspace → Organization → Global settings

List Integrations

Returns all integration configurations at the organization level.

GET /api/v1/organizations/{org_id}/integrations
Authorization: Bearer <token>

Requires admin role.

Response 200 OK

[
  {
    "id": "uuid",
    "integration_type": "smtp",
    "organization_id": "uuid",
    "enabled": true,
    "config": {
      "host": "smtp.company.com",
      "port": 587,
      "username": "noreply@company.com",
      "use_tls": true,
      "from_email": "noreply@company.com",
      "from_name": "Forgexa"
    },
    "created_at": "2026-05-16T00:00:00Z"
  },
  {
    "id": "uuid",
    "integration_type": "jira",
    "organization_id": "uuid",
    "enabled": true,
    "config": {
      "base_url": "https://acme.atlassian.net",
      "email": "bot@acme.com"
    },
    "created_at": "2026-05-16T00:00:00Z"
  }
]

Create or Update Integration

Create a new integration or update an existing one at the organization level.

POST /api/v1/organizations/{org_id}/integrations
Authorization: Bearer <token>
Content-Type: application/json

{
  "integration_type": "smtp",
  "config": {
    "host": "smtp.company.com",
    "port": 587,
    "username": "noreply@company.com",
    "password": "app-password",
    "use_tls": true,
    "from_email": "noreply@company.com",
    "from_name": "Forgexa Notifications"
  },
  "enabled": true
}

Response 201 Created

Requires admin role.

Delete Integration

DELETE /api/v1/organizations/{org_id}/integrations/{integration_type}
Authorization: Bearer <token>

Response 204 No Content

Requires admin role.

Supported Integration Types

Type	Description	Typical Scope
smtp	Email sending for invitations and notifications	Organization
jira	Issue tracker integration	Organization / Workspace
github	Repository and PR integration	Workspace / Project
git	Generic Git hosting (GitLab, Gitea, etc.)	Workspace / Project

Configuration Inheritance

When a workspace or project needs an integration, the system resolves configuration in order: Project → Workspace → Organization → Global settings. Configure shared services like SMTP at the organization level, and project-specific integrations (like GitHub repos) at the workspace or project level.