# Register a Git provider for the organization

> Organization owners (`org.manage`). Members of the organization then connect their account to it (`/auth/git/{ref}/start`) and the workspaces of its teams use it. Register an OAuth2 application at the provider first, with the redirect URI `https://<console>/auth/git/<ref>/callback`. The URL must be `https://`; loopback and link-local addresses (cloud metadata), names inside the cluster (`*.svc`, `*.<cluster domain>`), single-label names and IP literals of private ranges are refused with 422 `git-provider-url-refused`, whose `detail` says why. 409 `name-taken` when the organization has a provider with this id or URL, or the installation has a provider with this id. Registering a retired id again brings it back with the new fields. At most 20 active providers per organization (422).

URL: https://docs.harthelm.dev/reference/api/git/create-org-git-provider/ · Harthelm v1.6.1

## POST /api/v1/orgs/{org}/git-providers

Operation `createOrgGitProvider` · area `git` · credentials: the cookie `__Host-harthelm_session`, the header `Harthelm-Authorization` or `Authorization: Bearer`

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `org` | path | string, uuid | yes |  |
| `Idempotency-Key` | header | string | no | Client-chosen key (at most 255 characters); a repeated key returns the first result for 24 h. |

### Request body

`application/json`, required: OrgGitProviderCreate.

- `id` (OrgGitProviderID, required): A provider's id within its organization; its ref is `<id>-<ref suffix>`.
- `kind` (string): Gitea; Forgejo speaks the same API. One of `gitea`. Default `"gitea"`.
- `name` (string, required)
- `url` (string, required): https://host[:port][/path], no query.
- `client_id` (string, required)
- `client_secret` (string, password, required, write-only)
- `ca_pem` (string, write-only): PEM certificates of a private CA.

### Responses

| Status | Description | Body |
|---|---|---|
| 201 | The provider. | `application/json`: OrgGitProvider |
| 400 | The request is malformed. | `application/problem+json`: Problem |
| 401 | No or invalid credentials. | `application/problem+json`: Problem |
| 403 | The caller may not do this, or a CSRF check failed. | `application/problem+json`: Problem |
| 404 | The resource does not exist or is not visible to the caller. | `application/problem+json`: Problem |
| 409 | The request conflicts with the current state; `type` names the conflict. | `application/problem+json`: Problem |
| 422 | The request is well-formed but invalid; `errors` points at the fields. | `application/problem+json`: Problem |

### Response body (201)

- `id` (OrgGitProviderID, required): A provider's id within its organization; its ref is `<id>-<ref suffix>`.
- `ref` (GitProviderIDValue, required): The provider id everywhere else (`/auth/git/{ref}`, `GET /git/providers`, git access, the proxy path).
- `org_id` (string, uuid, required)
- `kind` (string, required): One of `gitea`.
- `name` (string, required)
- `url` (string, required): Web URL of the provider (https).
- `client_id` (string, required)
- `client_secret_set` (boolean, required): The OAuth client secret is stored (it is never returned).
- `ca_set` (boolean, required): A CA (PEM) for the provider's HTTPS is stored.
- `redirect_uri` (string, required): Register this at the provider's OAuth2 application.
- `created_by` (UserRef): A user as member lists show them.
  - `id` (ID, required): Numeric resource id.
  - `name` (string, required)
  - `email` (string, required)
  - `picture_url` (string)
- `created_at` (string, date-time, required)
- `updated_at` (string, date-time, required)
- `retired_at` (string, date-time): Only with include_retired, on a retired provider.