# Pontos de extremidade da API REST para chaves de implantação

Use a API REST para criar e gerenciar chaves de implantação.

## Sobre as chaves de implantação

É possível iniciar projetos por meio de um repositório no sua instância do GitHub Enterprise Server ao servidor usando uma chave de implantação, que é uma chave SSH que concede acesso a um só repositório. O GitHub anexa a parte pública da chave diretamente ao repositório em vez de a uma conta pessoal, e a parte privada da chave permanece no seu servidor. Para saber mais, confira [Realização de implantações](/pt/enterprise-server@3.18/rest/guides/delivering-deployments).

As chaves de implantação podem ser configuradas usando os pontos de extremidade de API a seguir, ou a interface da Web GitHub. Para saber como configurar chaves de implantação na interface da Web, confira [Gerenciar chaves de implantação](/pt/enterprise-server@3.18/authentication/connecting-to-github-with-ssh/managing-deploy-keys).

Talvez você não consiga criar chaves de implantação se o proprietário da sua organização ou empresa tiver definido uma política para restringir seu uso. Além disso, se essa política estiver habilitada no nível da organização ou da empresa, as chaves de implantação existentes poderão ser desabilitadas. Para saber mais, confira [Aplicar as políticas de gerenciamento do repositório na sua empresa](/pt/enterprise-server@3.18/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-repository-management-policies-in-your-enterprise#enforcing-a-policy-for-deploy-keys) e [Restringindo chaves de implantação em sua organização](/pt/enterprise-server@3.18/organizations/managing-organization-settings/restricting-deploy-keys-in-your-organization).

Há alguns casos em que uma chave de implantação será excluída por outra atividade:

* Se a chave de implantação for criada com uma personal access token, excluir o personal access token também excluirá a chave de implantação. A regeneração de personal access token não excluirá a chave de implantação.
* Se a chave de implantação for criada com um OAuth app token, a revogação do token também excluirá a chave de implantação.

Por outro lado, essas atividades não excluirão uma chave de implantação:

* Se a chave de implantação for criada com um GitHub App token de acesso do usuário, a revogação do token não excluirá a chave de implantação.
* Se a chave de implantação for criada com um GitHub App token de acesso de instalação, desinstalar ou excluir o aplicativo não excluirá a chave de implantação.
* Se a chave de implantação for criada com um personal access token, regenerar o personal access token não excluirá a chave de implantação.

> \[!NOTE]
> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2022-11-28`. Curl examples below omit these standard headers for brevity.

## List deploy keys

```
GET /repos/{owner}/{repo}/keys
```

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

* **`per_page`** (integer)
  The number of results per page (max 100). For more information, see "Using pagination in the REST API."
  Default: `30`

* **`page`** (integer)
  The page number of the results to fetch. For more information, see "Using pagination in the REST API."
  Default: `1`

### HTTP response status codes

* **200** - OK

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys
```

**Response schema (Status: 200):**

Array of `Deploy Key`:

* `id`: required, integer
* `key`: required, string
* `url`: required, string
* `title`: required, string
* `verified`: required, boolean
* `created_at`: required, string
* `read_only`: required, boolean
* `added_by`: string or null
* `last_used`: string or null, format: date-time
* `enabled`: boolean

## Create a deploy key

```
POST /repos/{owner}/{repo}/keys
```

You can create a read-only deploy key.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

#### Body parameters

* **`title`** (string)
  A name for the key.

* **`key`** (string) (required)
  The contents of the key.

* **`read_only`** (boolean)
  If true, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.
  Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see "Repository permission levels for an organization" and "Permission levels for a user account repository."

### HTTP response status codes

* **201** - Created

* **422** - Validation failed, or the endpoint has been spammed.

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X POST \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys \
  -d '{
  "title": "octocat@octomac",
  "key": "ssh-rsa AAA...",
  "read_only": true
}'
```

**Response schema (Status: 201):**

* `id`: required, integer
* `key`: required, string
* `url`: required, string
* `title`: required, string
* `verified`: required, boolean
* `created_at`: required, string
* `read_only`: required, boolean
* `added_by`: string or null
* `last_used`: string or null, format: date-time
* `enabled`: boolean

## Get a deploy key

```
GET /repos/{owner}/{repo}/keys/{key_id}
```

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

* **`key_id`** (integer) (required)
  The unique identifier of the key.

### HTTP response status codes

* **200** - OK

* **404** - Resource not found

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys/KEY_ID
```

**Response schema (Status: 200):**

Same response schema as [Create a deploy key](#create-a-deploy-key).

## Delete a deploy key

```
DELETE /repos/{owner}/{repo}/keys/{key_id}
```

Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.

### Parameters

#### Headers

* **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

* **`owner`** (string) (required)
  The account owner of the repository. The name is not case sensitive.

* **`repo`** (string) (required)
  The name of the repository without the .git extension. The name is not case sensitive.

* **`key_id`** (integer) (required)
  The unique identifier of the key.

### HTTP response status codes

* **204** - No Content

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys/KEY_ID
```

**Response schema (Status: 204):**