# Integrations

Integrations allow you to securely store and manage credentials for external services like **Jira** and **GitHub**. These credentials are encrypted at rest using AES-256 and can be scoped to specific projects or made globally available.

## Key Concepts

### What is an Integration?

An integration is a secure credential store that connects sfp server to external services. For example:

* **Jira integration**: Stores your Jira API credentials so sfp can fetch work items, link commits to issues, and track deployment status
* **GitHub integration**: Stores GitHub tokens for repository access, PR comments, and status checks

### Global vs Project-Scoped Integrations

| Scope                                  | Use Case                                             | Example                    |
| -------------------------------------- | ---------------------------------------------------- | -------------------------- |
| **Global** (`isGlobal: true`)          | Single set of credentials shared across all projects | Company-wide Jira instance |
| **Project-scoped** (`projects: [...]`) | Credentials specific to certain repositories         | Per-repo GitHub App tokens |

**When to use global integrations:**

* You have one Jira instance for all projects
* You want a fallback credential when no project-specific one exists

**When to use project-scoped integrations:**

* Different teams use different Jira projects
* You need separate GitHub tokens per repository
* Security requires credential isolation between projects

## Authentication Types

| Type         | Provider     | Use Case                                       |
| ------------ | ------------ | ---------------------------------------------- |
| `pat`        | GitHub       | Personal Access Token for API access           |
| `oauth`      | GitHub, Jira | OAuth flow for user-delegated access           |
| `app`        | GitHub       | GitHub App installation token                  |
| `basic_auth` | Jira         | Email + API token (recommended for Jira Cloud) |

## API Reference

### Create Integration

Register a new integration with encrypted credentials.

```
POST /sfp/api/integrations
```

**Request Body:**

| Field         | Type      | Required | Description                                                 |
| ------------- | --------- | -------- | ----------------------------------------------------------- |
| `provider`    | string    | Yes      | Service provider: `github` or `jira`                        |
| `authType`    | string    | Yes      | Authentication type: `pat`, `oauth`, `app`, or `basic_auth` |
| `credentials` | object    | Yes      | Provider-specific credentials (see examples below)          |
| `isGlobal`    | boolean   | No       | Set `true` for global integration                           |
| `projects`    | string\[] | No       | Project identifiers (required if not global)                |
| `config`      | object    | No       | Provider-specific configuration                             |

**Example: Global Jira Integration**

```bash
curl -X POST https://your-server/sfp/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "jira",
    "authType": "basic_auth",
    "credentials": {
      "base_url": "https://your-company.atlassian.net",
      "username": "your-email@company.com",
      "api_token": "your-jira-api-token"
    },
    "isGlobal": true
  }'
```

**Example: Project-Scoped GitHub Integration**

```bash
curl -X POST https://your-server/sfp/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "authType": "pat",
    "credentials": {
      "token": "ghp_xxxxxxxxxxxx"
    },
    "projects": ["your-org/sf-core", "your-org/sf-sales"]
  }'
```

### Get Credentials

Retrieve stored credentials for use in automation. All access is audited.

```
GET /sfp/api/integrations/credentials?provider={provider}&project={project}
```

**Query Parameters:**

| Parameter  | Required | Description                           |
| ---------- | -------- | ------------------------------------- |
| `provider` | No       | Filter by provider (`github`, `jira`) |
| `project`  | No       | Filter by project identifier          |

**Example:**

```bash
# Get Jira credentials for a specific project
curl "https://your-server/sfp/api/integrations/credentials?provider=jira&project=your-org/sf-core" \
  -H "Authorization: Bearer $TOKEN"
```

**Response:**

```json
[
  {
    "integration_id": "uuid-here",
    "provider": "jira",
    "auth_type": "basic_auth",
    "credentials": {
      "base_url": "https://your-company.atlassian.net",
      "username": "your-email@company.com",
      "api_token": "your-jira-api-token"
    }
  }
]
```

## Complete Workflow Example

Here's a typical setup workflow for a new team:

### 1. Register Your Project

```bash
sfp server project create \
  --identifier "acme-corp/salesforce-main" \
  --remote-url "https://github.com/acme-corp/salesforce-main"
```

### 2. Create a Global Jira Integration

Since most teams share a single Jira instance:

```bash
curl -X POST https://your-server/sfp/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "jira",
    "authType": "basic_auth",
    "credentials": {
      "base_url": "https://acme.atlassian.net",
      "username": "sfp-service@acme.com",
      "api_token": "ATATT3xFfGF0..."
    },
    "isGlobal": true
  }'
```

### 3. Create Project-Scoped GitHub Integration

For repository-specific access:

```bash
curl -X POST https://your-server/sfp/api/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "authType": "pat",
    "credentials": {
      "token": "ghp_xxxx"
    },
    "projects": ["acme-corp/salesforce-main"]
  }'
```

### 4. Use in Your Pipeline

Once configured, sfp commands automatically use the stored credentials:

```bash
# Work items are fetched using stored Jira credentials
sfp work-items list --project "acme-corp/salesforce-main"
```

## Security Considerations

* **Encryption**: All credentials are encrypted at rest using AES-256 via Supabase pgcrypto
* **Audit Logging**: Every credential access is logged with actor information
* **Least Privilege**: Use project-scoped integrations when possible to limit blast radius
* **Token Rotation**: Regularly rotate API tokens and update integrations accordingly

## Troubleshooting

### "Either isGlobal or projects must be specified"

You must specify either `isGlobal: true` OR provide a `projects` array. You cannot omit both.

### "Project 'xyz' not found"

The project identifier must match an existing registered project. List projects first:

```bash
sfp server project list
```

### "No integration found for project=xyz"

Either no integration exists for that project, or the integration is not scoped to include it. Check if a global integration exists or create a project-scoped one.


---

# 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/collaborate/integrations.md?ask=<question>
```

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.