--- title: "Connect an installed app" canonical: "https://admiral.io/docs/api/integrations/IntegrationAPI_ConnectIntegration" --- # Connect an installed app `POST https://api.admiral.io/v1/integrations/connect` The integration's name is the vendor account's login, lowercased. - INVALID_ARGUMENT when the callback variant does not match `kind`. - FAILED_PRECONDITION when the state is invalid or expired, or the vendor rejected the code. Install again. - PERMISSION_DENIED when the state belongs to another organization or user, or the installation is not the user's. - ALREADY_EXISTS when another organization holds this installation. - OK with the existing integration when this organization already holds it, including a reinstall of a disconnected one. Scope: `integration:write` ### Request body - `kind` (Kind, required): enum.defined_only = true One of `KIND_GITHUB`. - `state` (string, required): `state` from the callback query, as InstallIntegration issued it. Length 1 to 2048. - `code` (string, required): `code` from the callback query: the vendor's single-use user authorization code. Length 1 to 256. - `github` (GitHubInstallCallback): GitHubInstallCallback is what GitHub's callback carries beyond code and state. - `installation_id` (string (int64), required): `installation_id` from the callback query. ### Response 200 Success - `integration` (Integration): Integration is a connection your organization holds to an outside service. - `id` (string): Pattern `^int-[0-9a-z]+$`. Read-only. - `name` (string): Unique within the organization. Derived from the vendor account for an installed kind, so it may start with a digit. Pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63. Read-only. - `kind` (Kind): (IMMUTABLE) One of `KIND_UNSPECIFIED`, `KIND_GITHUB`. - `status` (Status): One of `STATUS_UNSPECIFIED`, `STATUS_CONNECTED`, `STATUS_NEEDS_ATTENTION`, `STATUS_DISCONNECTED`. Read-only. - `status_reason` (string): Why, and when, the status last left CONNECTED. Empty while connected. Read-only. - `settings` (IntegrationSettings): The block for `kind`. Exactly one variant is populated. - `github` (GitHubIntegrationSettings): GitHubIntegrationSettings describes one installation of Admiral's GitHub App. GitHub is the source of every field, so all of it is read only. - `installation_id` (string (int64)): GitHub's id for the installation. Read-only. - `account_login` (string): The login of the organization or user the App is installed on, as GitHub spells it. Read-only. - `account_type` (AccountType): AccountType is what the App is installed on. One of `ACCOUNT_TYPE_UNSPECIFIED`, `ACCOUNT_TYPE_ORGANIZATION`, `ACCOUNT_TYPE_USER`. Read-only. - `repository_selection` (RepositorySelection): RepositorySelection is how the installation was scoped on GitHub. One of `REPOSITORY_SELECTION_UNSPECIFIED`, `REPOSITORY_SELECTION_ALL`, `REPOSITORY_SELECTION_SELECTED`. Read-only. - `repositories` (array of string): Full names, `owner/name`, when the selection is SELECTED. Empty when it is ALL, and empty on a DISCONNECTED integration. Read-only. - `url` (string): The page on GitHub where the installation is managed. Empty on a DISCONNECTED integration. Read-only. - `suspended_at` (Timestamp): Set while GitHub has the installation suspended. Read-only. - `created_by` (ActorRef): Who connected it. Read-only. - `id` (string): The actor's typed id: a `usr-` user id or an `sa-` service account id. - `display_name` (string): Human-readable name (e.g., "John Smith", "deploy-bot"). - `email` (string): Email address (empty for non-human actors). - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only. - `updated_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only.