# Create an SCM App installation intent

**POST** `/v1/scm-installations/install-intents`

⚠️ Experimental endpoint: this API is in active development and may change at any time without notice. ⚠️

Creates an installation intent for the given workspace. If an existing installation can be proven to belong to the caller it is linked immediately (`alreadyLinked`); otherwise the response carries a URL the user opens to install the SCM app. Pass `repository` (owner/name) so an installation that already covers it but cannot be linked automatically is detected and explained in `hint`. Currently only `github` is supported.

Base URL: `https://api.prisma.io`

Tags: `[Experimental]`

## Authorization

Any ONE of the following options authorizes this operation; every scheme listed within an option is required together.

| Option | Scheme | Type | Sent as | Scopes |
| --- | --- | --- | --- | --- |
| Option 1 | `OAuth2` | `oauth2` | `Authorization: Bearer <access token>` | `offline_access`, `workspace:admin` |
| Option 2 | `Bearer` | `http` | `Authorization: Bearer <token>` (JWT) | — |

### OAuth 2.0 flows

- **OAuth2 · authorizationCode**
  - Authorization URL: `https://auth.prisma.io/authorize`
  - Token URL: `https://auth.prisma.io/token`
  - Refresh URL: `https://auth.prisma.io/token`
  - Scope `offline_access` — Offline access
  - Scope `workspace:admin` — Full access to workspace resources

## Request body

Optional. Media type: `application/json`

### Example request body

```json
{
  "provider": "github",
  "repository": "string",
  "workspaceId": "string"
}
```

## Responses

| Status | Description | Media type |
| --- | --- | --- |
| `201` | Installation intent created. The `installUrl` is single-use and time-limited. | `application/json` |
| `401` | Missing or invalid authorization token. | `application/json` |
| `403` | Workspace integration tokens cannot create install intents; a user-authenticated request is required. | `application/json` |
| `404` | Workspace not found or not accessible. | `application/json` |
| `422` | Validation failed (e.g. malformed workspaceId or unsupported provider). | `application/json` |
| `429` | Rate limit exceeded. | `application/json` |

### Example response: 201 — Installation intent created. The `installUrl` is single-use and time-limited.

```json
{
  "data": {
    "accountLogin": "string",
    "alreadyLinked": true,
    "hint": "string",
    "installUrl": "https://example.com",
    "provider": "github",
    "type": "install-intent",
    "workspaceId": "string"
  }
}
```

### Example response: 401 — Missing or invalid authorization token.

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

### Example response: 403 — Workspace integration tokens cannot create install intents; a user-authenticated request is required.

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

### Example response: 404 — Workspace not found or not accessible.

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

### Example response: 422 — Validation failed (e.g. malformed workspaceId or unsupported provider).

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

### Example response: 429 — Rate limit exceeded.

```json
{
  "error": {
    "code": "string",
    "hint": "string",
    "message": "string"
  }
}
```

## Related pages

- [[Experimental]](./tags/experimental.md)
- [Acquire Alchemy deploy lease](./postv1projectsbyprojectidbranchesbybranchidalchemy-statelease.md)
- [Agents](./tags/agents.md)
- [Alchemy state store version](./getv1projectsbyprojectidbranchesbybranchidalchemy-stateversion.md)
- [Buckets](./tags/buckets.md)
- [Connections](./tags/connections.md)
- [Create a branch](./postv1projectsbyprojectidbranches.md)
- [Create a custom domain](./postv1appsbyappiddomains.md)
- [Create a custom domain](./postv1servicesbyserviceiddomains.md)
- [Create a workspace](./postv1workspaces.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.