# 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.9.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 Owner 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: ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.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\", entra_authority_url: \"https://login.microsoftonline.com\" }\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 Owner 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"}},"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.9.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.9.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.9.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.9.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.9.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"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/integrations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.