---
# @generated by sylphx-gen. Do not edit.
title: "Begin registration on a connection provider"
description: "`connections.connection_providers.begin_registration` (POST /v1/{parent}/connection_providers:beginRegistration): Begins an expiring, one-use GitHub manifest registration ceremony."
type: reference
product: platform
summary: "Begins an expiring, one-use GitHub manifest registration ceremony."
updated: 2026-09-28
nav: false
---

Begins an expiring, one-use GitHub manifest registration ceremony. Open registration_url to POST the bound, prefilled manifest to GitHub. github_organization selects organization ownership. The state-authorized callback is GET /v1/connections/github-manifest:callback?state=...&code=... and returns only provider metadata and an installation URL.

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/connection_providers:beginRegistration`
- **Scope** `connections:admin`
- **Effect** `write` — a successful call changes state.
- **Collection** [connection_providers](/docs/api/connection_providers)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `parent` | `string` | The organization that will own the provider and custody references. Required. |
| `connection_provider_id` | `string` | Explicit immutable provider identity. Required. |
| `signing_key` | `string` | Unused environment-scoped public Keys target in this organization. Required. |
| `webhook_secret` | `string` | Environment-scoped Secrets custody target in this organization. Required. |
| `github_manifest` | `GitHubAppManifest` | Permissions, events and the declared platform webhook destination. Required. |
| `expected_github_app_slug` | `string` | Slug whose literal wrapped-import path has been enrolled in custody. Renaming the App at GitHub causes the callback to refuse before import. Required. |
| `github_organization` | `string` | GitHub organization that will own the App; unset selects a personal account. |

### GitHubAppManifest

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | Proposed GitHub display name. Required. |
| `url` | `string` | HTTPS homepage, not an OAuth callback or webhook destination. Required. |
| `public` | `bool` | Whether other accounts may install the App. This is GitHub's own manifest key, which clients must read and write verbatim; the JSON, SDK, CLI and Terraform names therefore stay `public` too. |
| `default_permissions` | `map<string, string>` | GitHub read/write permissions; metadata:read is always included. Required. |
| `default_events` | `string[]` | GitHub webhook events to subscribe to. Required. |
| `hook_attributes` | `GitHubManifestHookAttributes` | Only declared receiving endpoints on the platform origin are accepted. Required. |

### GitHubManifestHookAttributes

| Field | Type | What it is |
| --- | --- | --- |
| `url` | `string` | https://api.sylphx.com/v1/orgs/&#123;org&#125;/connection_providers/&#123;provider&#125;/github:webhook; org and provider must match this registration's parent and provider id. Required. |
| `active` | `bool` | Must be true: deliveries verify the generated secret at the receiver. Required. |

## Response

| Field | Type | What it is |
| --- | --- | --- |
| `state` | `string` | Cryptographic one-use capability; never log or persist client-side. |
| `callback_url` | `string` | Actual state-authorized callback, requiring no ordinary Access bearer. |
| `registration_url` | `string` | Open with GET: launches the stored manifest POST to GitHub, including state. |
| `manifest` | `string` | JSON-encoded normalized intent, for inspecting the requested configuration. |
| `expire_time` | `timestamp` | State expires ten minutes after begin. |

## Errors

- [`UNAUTHENTICATED`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`INVALID_FIELD`](/docs/api/errors/INVALID_FIELD) — A field failed validation.
- [`INVALID_STATE`](/docs/api/errors/INVALID_STATE) — The Resource is in a state that forbids the call.
- [`RESOURCE_ALREADY_EXISTS`](/docs/api/errors/RESOURCE_ALREADY_EXISTS) — A Resource with this name exists.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

```curl
curl -X POST "https://api.sylphx.com/v1/orgs/acme/connection_providers:beginRegistration" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connection_provider_id":"…","expected_github_app_slug":"…","github_manifest":{"default_events":["…"],"default_permissions":{},"hook_attributes":{"active":false,"url":"…"},"name":"…","url":"…"},"signing_key":"…","webhook_secret":"…"}'
```

**TypeScript**

```ts
const response = await sylphx.connections.connectionProviders.beginRegistration({ connectionProviderId: '…', expectedGithubAppSlug: '…', githubManifest: { defaultEvents: ['…'], defaultPermissions: {}, hookAttributes: { active: false, url: '…' }, name: '…', url: '…' }, parent: 'orgs/acme', signingKey: '…', webhookSecret: '…' })
```

**Rust**

```rust
let mut req = sylphx::connections::BeginConnectionProviderRegistrationRequest::default();
req.connection_provider_id = "…".to_string();
req.expected_github_app_slug = "…".to_string();
req.github_manifest = Some(sylphx::connections::GitHubAppManifest {
    default_events: vec!["…".to_string()],
    default_permissions: Some(Default::default()),
    hook_attributes: Some(sylphx::connections::GitHubManifestHookAttributes {
        active: false,
        url: "…".to_string(),
        ..Default::default()
    }),
    name: "…".to_string(),
    url: "…".to_string(),
    ..Default::default()
});
req.parent = "orgs/acme".to_string();
req.signing_key = "…".to_string();
req.webhook_secret = "…".to_string();
let response = sx.connections().connection_providers().begin_registration(req).await?;
```

**CLI**

```bash
sylphx connections connection-providers begin-registration orgs/acme
```

**MCP**

```json
{ "method_id": "connections.connection_providers.begin_registration", "args": {"connection_provider_id":"…","expected_github_app_slug":"…","github_manifest":{"default_events":["…"],"default_permissions":{},"hook_attributes":{"active":false,"url":"…"},"name":"…","url":"…"},"parent":"orgs/acme","signing_key":"…","webhook_secret":"…"} }
```