# Integrations

## List all integrations

> List all configured integrations. Returns integration metadata without credentials.\
> \
> \*\*Authentication\*\*: Requires Owner role. This endpoint is for administrative purposes to view and manage integrations.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/integrations":{"get":{"operationId":"IntegrationsController_list","summary":"List all integrations","description":"List all configured integrations. Returns integration metadata without credentials.\n\n**Authentication**: Requires Owner role. This endpoint is for administrative purposes to view and manage integrations.","parameters":[{"name":"provider","required":false,"in":"query","description":"Filter by provider: `github` or `jira`","schema":{"enum":["github","azuredevops","jfrog","gitlab","npm","github_packages","jira","azure-devops","ai_anthropic","ai_openai","ai_google","ai_github_copilot","ai_amazon_bedrock","datadog","newrelic","splunk"],"type":"string"}}],"responses":{"200":{"description":"List of integrations"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Integrations"]}}}}
```

## Store credentials for external services (Jira, GitHub)

> Securely store credentials for external integrations. Credentials are encrypted at rest using AES-256.\
> \
> \*\*Authentication\*\*: Requires user authentication (Owner or Member role). Application tokens are not permitted for credential creation.\
> \
> \*\*Scope options:\*\*\
> \- \*\*Global\*\* (\`isGlobal: true\`): Credentials available to all projects. Use for shared services like a company-wide Jira.\
> \- \*\*Project-scoped\*\* (\`projects: \[...]\`): Credentials only for specific repositories. Projects must be registered first via \`POST /projects\`.\
> \
> \*\*Common setups:\*\*\
> \- Jira: \`provider: "jira", authType: "basic\_auth", credentials: { base\_url, username, api\_token }\`\
> \- GitHub PAT: \`provider: "github", authType: "pat", credentials: { token }\`\
> \
> See full guide: <https://docs.flxbl.io/sfp/api-reference/integrations>

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"CreateIntegrationDto":{"type":"object","properties":{"provider":{"$ref":"#/components/schemas/IntegrationProvider"},"authType":{"$ref":"#/components/schemas/IntegrationAuthType"},"credentials":{"type":"object","description":"Provider-specific credentials. Examples:\n        - GitHub PAT: { token: \"ghp_xxx\" }\n        - GitHub App: { appId: \"123456\", privateKey: \"-----BEGIN RSA...\" }\n        - GitHub OAuth App: { client_id: \"Iv1.xxx\", client_secret: \"xxx\" }\n        - Azure DevOps PAT: { organization_url: \"https://dev.azure.com/org\", token: \"xxx\" }\n        - Azure DevOps Service Principal: { organization_url: \"https://dev.azure.com/org\", client_id: \"xxx\", client_secret: \"xxx\", tenant_id: \"xxx\" }\n        - Jira basic_auth: { base_url: \"https://company.atlassian.net\", username: \"email\", api_token: \"token\" }\n        - Jira oauth_client_credentials: { client_id: \"...\", client_secret: \"...\", cloud_id: \"...\" }\n        - AI Anthropic: { api_key: \"sk-ant-...\" }\n        - AI OpenAI: { api_key: \"sk-...\" }\n        - AI Google: { api_key: \"...\" }\n        - AI GitHub Copilot: { token: \"ghu_...\" }\n        - AI Amazon Bedrock: { bearer_token: \"...\", region: \"us-east-1\" }\n        - DataDog: { api_key: \"dd-xxx\" }  (config: { site: \"datadoghq.com\" })\n        - New Relic: { api_key: \"NRAK-xxx\" }  (config: { region: \"US\" })\n        - Splunk: { api_key: \"splunk-hec-token\" }  (config: { host: \"https://input-prd-xxx.cloud.splunk.com:8088\" })"},"projects":{"description":"Repository identifiers to scope this integration to. Get these from `GET /projects` or register via `POST /projects`. Required if `isGlobal` is false.","type":"array","items":{"type":"string"}},"isGlobal":{"type":"boolean","description":"Set `true` to make credentials available to ALL projects. Use for shared services like a company-wide Jira instance. Either `isGlobal` or `projects` must be specified."},"isDefault":{"type":"boolean","description":"Mark as the system default for this provider category. Only global integrations can be default. AI providers are grouped — setting one AI provider as default unsets any other AI default.","default":false},"config":{"type":"object","description":"Provider-specific configuration options"}},"required":["provider","authType","credentials"]},"IntegrationProvider":{"type":"string","description":"External service to integrate with","default":"github","enum":["github","azuredevops","jfrog","gitlab","npm","github_packages","jira","azure-devops","ai_anthropic","ai_openai","ai_google","ai_github_copilot","ai_amazon_bedrock","datadog","newrelic","splunk"]},"IntegrationAuthType":{"type":"string","description":"How to authenticate with the provider:\n- `pat` for GitHub/Azure DevOps tokens\n- `basic_auth` for Jira (email + API token)\n- `oauth_client_credentials` for Jira OAuth 2.0 (client_id + client_secret + cloud_id)\n- `service_principal` for Azure DevOps (client_id + client_secret + tenant_id)\n- `app` for GitHub App\n- `oauth` for OAuth flows\n- `api_key` for AI providers (Anthropic, OpenAI, Google)\n- `bearer` for AWS Bedrock","default":"pat","enum":["pat","oauth","app","basic","basic_auth","oauth_client_credentials","service_principal","api_key","bearer"]}}},"paths":{"/sfp/api/integrations":{"post":{"operationId":"IntegrationsController_create","summary":"Store credentials for external services (Jira, GitHub)","description":"Securely store credentials for external integrations. Credentials are encrypted at rest using AES-256.\n\n**Authentication**: Requires user authentication (Owner or Member role). Application tokens are not permitted for credential creation.\n\n**Scope options:**\n- **Global** (`isGlobal: true`): Credentials available to all projects. Use for shared services like a company-wide Jira.\n- **Project-scoped** (`projects: [...]`): Credentials only for specific repositories. Projects must be registered first via `POST /projects`.\n\n**Common setups:**\n- Jira: `provider: \"jira\", authType: \"basic_auth\", credentials: { base_url, username, api_token }`\n- GitHub PAT: `provider: \"github\", authType: \"pat\", credentials: { token }`\n\nSee full guide: https://docs.flxbl.io/sfp/api-reference/integrations","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIntegrationDto"}}}},"responses":{"201":{"description":"Integration created successfully"},"400":{"description":"Invalid configuration, missing scope (isGlobal or projects), or project not found"},"401":{"description":"Application tokens not permitted - requires user authentication"},"403":{"description":"Forbidden - Requires role: owner, member"}},"tags":["Integrations"]}}}}
```

## List default integrations

> List all integrations marked as system defaults. One default per provider category (AI providers are grouped — only one default across all AI providers). Default integrations are used as fallback when a project has no project-specific integration.\
> \
> \*\*Authentication\*\*: Requires Owner role.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/integrations/defaults":{"get":{"operationId":"IntegrationsController_listDefaults","summary":"List default integrations","description":"List all integrations marked as system defaults. One default per provider category (AI providers are grouped — only one default across all AI providers). Default integrations are used as fallback when a project has no project-specific integration.\n\n**Authentication**: Requires Owner role.","parameters":[],"responses":{"200":{"description":"List of default integrations"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Integrations"]}}}}
```

## Retrieve stored credentials

> Fetch decrypted credentials for integrations. Returns credentials matching the filter criteria. All access is logged for audit purposes.\
> \
> \*\*Authentication\*\*: Requires Owner role or Application token. Application tokens must specify a \`provider\` or \`project\` filter to prevent unscoped credential enumeration.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/integrations/credentials":{"get":{"operationId":"IntegrationsController_getCredentials","summary":"Retrieve stored credentials","description":"Fetch decrypted credentials for integrations. Returns credentials matching the filter criteria. All access is logged for audit purposes.\n\n**Authentication**: Requires Owner role or Application token. Application tokens must specify a `provider` or `project` filter to prevent unscoped credential enumeration.","parameters":[{"name":"provider","required":false,"in":"query","description":"Filter by service: `github` or `jira`","schema":{"enum":["github","azuredevops","jfrog","gitlab","npm","github_packages","jira","azure-devops","ai_anthropic","ai_openai","ai_google","ai_github_copilot","ai_amazon_bedrock","datadog","newrelic","splunk"],"type":"string"}},{"name":"project","required":false,"in":"query","description":"Filter by registered project identifier (e.g., `flxbl-io/sf-core`). List projects via `GET /projects`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Credentials retrieved successfully"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"No integration found for the specified filters"}},"tags":["Integrations"]}}}}
```

## Delete an integration

> Permanently delete an integration and its encrypted credentials.\
> \
> \*\*Authentication\*\*: Requires Owner role. This action cannot be undone.\
> \
> \*\*Effects:\*\*\
> \- Removes the integration configuration\
> \- Deletes encrypted credentials from secure storage\
> \- Removes integration reference from associated projects\
> \- Logs deletion in audit trail

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/integrations/{id}":{"delete":{"operationId":"IntegrationsController_remove","summary":"Delete an integration","description":"Permanently delete an integration and its encrypted credentials.\n\n**Authentication**: Requires Owner role. This action cannot be undone.\n\n**Effects:**\n- Removes the integration configuration\n- Deletes encrypted credentials from secure storage\n- Removes integration reference from associated projects\n- Logs deletion in audit trail","parameters":[{"name":"id","required":true,"in":"path","description":"Integration ID (UUID)","schema":{"type":"string"}}],"responses":{"204":{"description":"Integration deleted successfully"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Integration not found"}},"tags":["Integrations"]}}}}
```

## Update an integration

> Update credentials, config, or default status of an existing integration. Only provided fields are updated — omitted fields remain unchanged.\
> \
> \*\*Authentication\*\*: Requires Owner role.\
> \
> \*\*Updatable fields:\*\*\
> \- \`credentials\`: New encrypted credentials (replaces existing)\
> \- \`config\`: Provider-specific configuration\
> \- \`isDefault\`: Toggle default status for this provider category\
> \
> \*\*Immutable fields\*\* (cannot be changed after creation):\
> \- \`provider\`\
> \- \`authType\`\
> \- \`projects\` / \`isGlobal\`

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"UpdateIntegrationDto":{"type":"object","properties":{"credentials":{"type":"object","description":"Updated credentials for the integration. Same format as create."},"config":{"type":"object","description":"Updated provider-specific configuration options"},"isDefault":{"type":"boolean","description":"Update default status for this provider category. AI providers are grouped — setting one AI provider as default unsets any other AI default."}}}}},"paths":{"/sfp/api/integrations/{id}":{"patch":{"operationId":"IntegrationsController_update","summary":"Update an integration","description":"Update credentials, config, or default status of an existing integration. Only provided fields are updated — omitted fields remain unchanged.\n\n**Authentication**: Requires Owner role.\n\n**Updatable fields:**\n- `credentials`: New encrypted credentials (replaces existing)\n- `config`: Provider-specific configuration\n- `isDefault`: Toggle default status for this provider category\n\n**Immutable fields** (cannot be changed after creation):\n- `provider`\n- `authType`\n- `projects` / `isGlobal`","parameters":[{"name":"id","required":true,"in":"path","description":"Integration ID (UUID)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateIntegrationDto"}}}},"responses":{"200":{"description":"Integration updated successfully"},"400":{"description":"Invalid update (e.g., setting non-global integration as default)"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Integration not found"}},"tags":["Integrations"]}}}}
```

## Check health of platform integrations for registered projects

> Verifies that the source control platform (GitHub or Azure DevOps) is reachable and that credentials are valid for each registered project.\
> \
> \## How it works\
> \
> Each project registered via \`POST /projects\` declares a \`platform\` field (\`github\` or \`azure-devops\`). This endpoint resolves the credentials for each project's platform and makes a lightweight API call to confirm access.\
> \
> \### Credential resolution\
> \
> \| Platform | What is checked |\
> \|----------|----------------|\
> \| \*\*GitHub\*\* | Uses the GitHub App credentials (user-configured integration first, falls back to built-in App from server environment). Calls \`GET /repos/{owner}/{repo}\` to confirm repository access. |\
> \| \*\*Azure DevOps\*\* | Uses the Service Principal credentials from the configured integration. Calls \`GET /\_apis/connectiondata\` to confirm API connectivity. |\
> \
> \### Modes\
> \
> \| Parameter | Behavior |\
> \|-----------|----------|\
> \| No \`project\` | Lists \*\*all\*\* registered projects and checks each one. Useful for a full integration health overview. |\
> \| \`project=flxbl-io/sf-core\` | Checks \*\*only\*\* the specified project. Useful for verifying a single onboarding. |\
> \
> \### Response statuses\
> \
> \| Overall status | Meaning |\
> \|---------------|---------|\
> \| \`healthy\` | All projects have working platform integrations |\
> \| \`degraded\` | Some projects are healthy, others are not |\
> \| \`unhealthy\` | No project has a working platform integration |\
> \
> \### Common failure causes\
> \
> \- \*\*GitHub\*\*: App not installed on the organization, or repository is private and not accessible to the App\
> \- \*\*Azure DevOps\*\*: Service Principal not registered via \`POST /integrations\`, invalid client credentials, or organization URL is wrong\
> \
> \### Authentication\
> Requires any authenticated role (Owner, Member, or Application token).

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"PlatformHealthResultDto":{"type":"object","properties":{"status":{"type":"string","description":"Overall health across all checked projects:\n- `healthy` — every project's platform integration is reachable\n- `degraded` — at least one project is healthy but others are unhealthy or not configured\n- `unhealthy` — no project has a healthy platform integration","enum":["healthy","degraded","unhealthy"]},"timestamp":{"type":"string","description":"ISO 8601 timestamp of when the health check was performed"},"platforms":{"description":"Per-project health check results. One entry per registered project with a supported platform (GitHub or Azure DevOps).","type":"array","items":{"$ref":"#/components/schemas/PlatformComponentHealthDto"}}},"required":["status","timestamp","platforms"]},"PlatformComponentHealthDto":{"type":"object","properties":{"provider":{"type":"string","description":"Source control platform for this project","enum":["github","azure-devops","none"]},"project":{"type":"string","description":"Project identifier that was checked"},"status":{"type":"string","description":"Health status of the platform integration for this project:\n- `healthy` — credentials are valid and the platform API confirmed access to the repository\n- `unhealthy` — credentials are missing, invalid, expired, or the platform API is unreachable\n- `not_configured` — no integration or project is registered for the requested platform\n- `initializing` — server recently started; token cache is still warming up (transient, resolves within ~60s)","enum":["healthy","unhealthy","not_configured","initializing"]},"message":{"type":"string","description":"Human-readable explanation of the health check result"},"latency":{"type":"number","description":"Round-trip time in milliseconds for the health check API call"}},"required":["provider","project","status","message"]}}},"paths":{"/sfp/api/integrations/platforms/health":{"get":{"operationId":"PlatformHealthController_checkHealth","summary":"Check health of platform integrations for registered projects","description":"Verifies that the source control platform (GitHub or Azure DevOps) is reachable and that credentials are valid for each registered project.\n\n## How it works\n\nEach project registered via `POST /projects` declares a `platform` field (`github` or `azure-devops`). This endpoint resolves the credentials for each project's platform and makes a lightweight API call to confirm access.\n\n### Credential resolution\n\n| Platform | What is checked |\n|----------|----------------|\n| **GitHub** | Uses the GitHub App credentials (user-configured integration first, falls back to built-in App from server environment). Calls `GET /repos/{owner}/{repo}` to confirm repository access. |\n| **Azure DevOps** | Uses the Service Principal credentials from the configured integration. Calls `GET /_apis/connectiondata` to confirm API connectivity. |\n\n### Modes\n\n| Parameter | Behavior |\n|-----------|----------|\n| No `project` | Lists **all** registered projects and checks each one. Useful for a full integration health overview. |\n| `project=flxbl-io/sf-core` | Checks **only** the specified project. Useful for verifying a single onboarding. |\n\n### Response statuses\n\n| Overall status | Meaning |\n|---------------|---------|\n| `healthy` | All projects have working platform integrations |\n| `degraded` | Some projects are healthy, others are not |\n| `unhealthy` | No project has a working platform integration |\n\n### Common failure causes\n\n- **GitHub**: App not installed on the organization, or repository is private and not accessible to the App\n- **Azure DevOps**: Service Principal not registered via `POST /integrations`, invalid client credentials, or organization URL is wrong\n\n### Authentication\nRequires any authenticated role (Owner, Member, or Application token).","parameters":[{"name":"project","required":false,"in":"query","description":"Project identifier to check (e.g., `flxbl-io/sf-core` for GitHub, `org/project/repo` for Azure DevOps). Omit to check all registered projects.","schema":{"type":"string"}}],"responses":{"200":{"description":"Platform health check results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformHealthResultDto"}}}},"401":{"description":"Unauthorized — missing or invalid bearer token"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Project not found — the specified project identifier does not exist"}},"tags":["Integrations"]}}}}
```