---
title: "API do GeCert"
description: "API REST do GeCert: autenticação, as rotas de chaves, certificados, acessos, repositórios, usos e relatórios com as permissões exigidas, a API usada pelo Gecert Connect e os códigos de erro."
canonical: "https://docs.lacunasoftware.com/articles/gecert/api"
locale: "pt-BR"
product: "GeCert"
last_updated: "2026-10-13"
---

# API do GeCert

A API REST do [GeCert](https://docs.lacunasoftware.com/articles/gecert) é a mesma que a aplicação web e o [Gecert Connect](https://docs.lacunasoftware.com/articles/gecert/gecert-connect) usam. A descrição completa das
rotas e dos modelos está no Swagger da sua instância, em `https://endereco-do-seu-gecert/swagger`. 

## Autenticação

As requisições levam o header `Authorization: Bearer SEU_TOKEN`, com um token de acesso emitido pelo [GrantID](https://docs.lacunasoftware.com/articles/grant-id) da
instância para a API do GeCert (a configuração `Oidc:ApiName` do servidor). É o mesmo token que a aplicação web obtém ao entrar e que o
Gecert Connect obtém no login. As rotas da área da organização operam na organização a que o usuário pertence, como a aplicação web.

Só as rotas de configuração do aplicativo são anônimas: 

| Rota | Resposta |
|---|---|
| `GET /api/app-configuration` | `{"hidePoweredBy": false}` |
| `GET /api/app-configuration/gecert-connect` | A versão mínima do Gecert Connect e se o servidor está em manutenção: `{"minSupportedVersion": "1.1.0.0", "underMaintenance": false}` |
| `GET /api/app-configuration/gecert-connect/server` | O endereço do servidor e os dados do GrantID para o Gecert Connect: `serverUrl`, `grantIdAuthority`, `grantIdClientAppId`, `grantIdApiName`, `grantIdRedirectUri`. Erro `GecertConnectServerNotConfigured` se a seção [`GecertConnect`](https://docs.lacunasoftware.com/articles/gecert/on-premises/configure-gecert-connect) não estiver preenchida |
| `GET /api/system/info` | O nome e a versão do produto: `{"productName":"Gecert","productVersion":"1.x.x"}` |

## Rotas

As listas (`.../list`) são paginadas e aceitam os parâmetros `q` (busca), `offset`, `limit` e `order`. A permissão de cada rota é
verificada na organização do recurso; na área Sys Admin, na raiz. 

### Chaves

| Rota | O que faz | Permissão |
|---|---|---|
| `GET /api/keys/list` | Lista as chaves da organização | `ViewKeys` |
| `GET /api/keys/available/list` | Lista as chaves que ainda não têm certificado | `ViewKeys` |
| `GET /api/keys/{id}/summary` | Resumo da chave: nome, organização, certificado e tipo do repositório | `ViewKeys` |
| `GET /api/keys/{id}/details` | Detalhes: tipo, tamanho e tipo do repositório. Responde com a falha `CannotRetrieveKeyFromKeyStore` quando a chave não é encontrada no repositório | `ViewKeys` |
| `GET /api/keys/{id}/csr` | A CSR guardada para a chave, em PEM, com o nome do titular e o algoritmo de hash | `ViewKeys` |
| `POST /api/keys/{id}/custom-csr` | Emite uma nova CSR para a chave. Corpo: `{"params": "CN=...,O=...", "hashAlgorithm": "SHA256"}` | `ManageKeys` |
| `GET /api/keys/{id}/parameters` | Os parâmetros da chave no repositório, em JSON. Erro `KeyStoreParametersNotAccessible` se o repositório não permite registro de chaves | `ViewKeys` |
| `GET /api/keys/{id}/parameters/accessible` | Se os parâmetros podem ser lidos (`true` ou `false`) | `ViewKeys` |
| `GET /api/keys/{id}/events` | Eventos da chave, paginados | `ViewKeys` |
| `PUT /api/keys` | Registra uma chave que já existe no repositório. Corpo: `{"parameters": {"keyStore": "...", "keyName": "...", "keyStoreParameters": {...}}}` ([veja abaixo](https://docs.lacunasoftware.com/articles/gecert/api#parâmetros-de-registro-de-chaves)) | `ManageKeys` |
| `PUT /api/keys/{id}` | Renomeia a chave. Corpo: `{"name": "..."}` | `ManageKeys` |
| `DELETE /api/keys/{id}` | Exclui a chave (e a apaga do repositório quando a [exclusão definitiva](https://docs.lacunasoftware.com/articles/gecert#repositórios-de-chaves) está configurada). Erro `GecertKeyHasActiveCertificate` se ela tem certificado | `ManageKeys` |

### Certificados

| Rota | O que faz | Permissão |
|---|---|---|
| `GET /api/certificates/list` | Lista os certificados da organização, com o número de usuários autorizados | `ViewCertificates` |
| `GET /api/certificates/{id}` | Detalhes: titular, emissor, tipo, e-mail, validade, *thumbprint* SHA-1 e o ID da chave | `ViewCertificates` |
| `GET /api/certificates/{id}/events` | Eventos do certificado, paginados | `ViewCertificates` |
| `GET /api/certificates/{id}/usage` | [Usos da chave](https://docs.lacunasoftware.com/articles/gecert/api#usos-de-chaves) do certificado, paginados | `ViewCertificates` |
| `GET /api/certificates/{id}/authorized-users` | Os usuários com acesso ao certificado, paginados | `ViewCertificateAccess` |
| `GET /api/certificates/{id}/public-bytes` | O certificado codificado (DER), em Base64 | Acesso ao certificado (`UseKey`) |
| `GET /api/certificates/my` | Os certificados a que o usuário autenticado tem acesso | Usuário autenticado |
| `POST /api/certificates` | Adiciona um certificado a partir de um PKCS #12 enviado antes como upload. Corpo: `{"blobId": "...", "keyStoreName": "...", "password": "..."}`. Falhas: `CertificatePasswordIsIncorrect`, `CertificateAlreadyExistsOnSubscription`, `CertificateIsExpectedToHaveRsaKeys` | `ManageCertificates` |
| `PUT /api/certificates` | Registra um certificado (`.cer`) para uma chave existente. Corpo: `{"blobId": "...", "keyId": "..."}`. Falhas: `CertificateIsNotExpectedToHavePassword`, `CertificateAlreadyExistsOnSubscription`, `KeysAreNotEquivalent` | `ManageCertificates` |
| `DELETE /api/certificates/{id}` | Exclui o certificado, os acessos a ele e a chave | `ManageCertificates` |

As respostas de `POST` e `PUT /api/certificates` seguem o formato `{"success": true, "id": "..."}` ou
`{"success": false, "failure": "CertificatePasswordIsIncorrect", "failureType": "NewCertificateResponseFailures"}`.

### Acessos a certificados

| Rota | O que faz | Permissão |
|---|---|---|
| `GET /api/certificate-access` | Lista os acessos da organização, paginados | `ViewCertificateAccess` |
| `POST /api/certificate-access` | Concede acesso. Corpo: `{"certificateId": "...", "userId": "..."}`. Falhas: `CertificateAccessAlreadyExists`, `UserNeedsSubscriptionAccess`, `UserHasAccessToThisCertificateInAnotherSubscription` | `ManageCertificateAccess` |
| `DELETE /api/certificate-access/{id}` | Remove um acesso | `ManageCertificateAccess` |
| `DELETE /api/certificate-access/certificates/{certificateId}` | Remove todos os acessos de um certificado | `ManageCertificateAccess` |
| `DELETE /api/certificate-access/users/{userId}` | Remove todos os acessos de um usuário na organização | `ManageCertificateAccess` |
| `POST /api/certificate-access/certificates/{de}/to/{para}` | Copia todos os acessos de um certificado para outro. A resposta traz uma lista com o resultado de cada usuário | `ManageCertificateAccess` nos dois certificados |
| `GET /api/users/{userId}/authorized-certificates` | Os certificados a que um usuário tem acesso | `ViewCertificateAccess` |
| `GET /api/users/{userId}/subscription-access/verification` | Se o usuário tem acesso à organização (`true` ou `false`) | `ViewCertificateAccess` |

### Repositórios de chaves

| Rota | O que faz | Permissão |
|---|---|---|
| `GET /api/key-stores` | Os repositórios a que a organização tem acesso: nome, tipo, se é o padrão, se aceita registro e inserção de chaves, exclusão definitiva, tamanhos de chave e padrão do nome | `ManageKeys` |
| `GET /api/key-stores/{type}/example` | Um exemplo dos parâmetros de registro para o tipo (`Kryptus`, `AzureKeyVault` ou `Pkcs11`) | `ManageKeys` |
| `GET /api/key-stores/list` | Todos os repositórios configurados na instância, paginados | `Read` na raiz (Sys Admin) |
| `GET /api/key-stores/details?name=...` | Os detalhes de um repositório, conforme o tipo: no Azure Key Vault, o endpoint, o ID do aplicativo e se usa HSM; no Kryptus, o host, a porta e os usuários; no PKCS #11, o módulo e o número de série do token | `Read` na raiz (Sys Admin) |
| `GET /api/subscriptions/my/key-stores` | Os acessos a repositórios da organização | `ManageKeys` |
| `GET /api/subscriptions/{id}/key-stores` | Os acessos a repositórios de uma organização, paginados | `ViewKeyStoreAccess` na raiz |
| `POST /api/key-store-access` | Concede a uma organização acesso a um repositório. Corpo: `{"subscriptionId": "...", "keyStoreName": "..."}`. Falha: `KeyStoreAccessAlreadyExists` | `ManageKeyStoreAccess` na raiz |
| `DELETE /api/key-store-access/{id}` | Remove o acesso. As chaves que já estão no repositório continuam funcionando | `ManageKeyStoreAccess` na raiz |

### Usos de chaves

| Rota | O que faz | Permissão |
|---|---|---|
| `GET /api/key-usages/list` | Os usos das chaves da organização, paginados: data, certificado, usuário, operação (`Encrypt`, `Decrypt`, `Sign` ou `Verify`), algoritmo, hash, valor e, nas verificações, se a assinatura era válida | `ViewCertificates` |

### Relatórios

| Rota | O que faz | Permissão |
|---|---|---|
| `POST /api/reports/certificates/expiration-date` | Gera o relatório de expiração dos certificados da organização (nome, e-mail e data de expiração). Corpo: `{"fileType": "Xlsx"}`, `"Csv"` ou `"Pdf"` | `ManageCertificates` |
| `POST /api/reports/certificates/{id}/events` | Gera o relatório dos eventos de um certificado (data, entidade, operação, detalhes, agente e organização) | `ManageCertificates` |
| `GET /api/reports/{id}?fileType=...` | Baixa o relatório gerado | Ticket de acesso devolvido na geração |

A geração responde com `{"success": true, "ticket": {"location": "..."}}`, e `location` é o endereço para baixar o arquivo; ou com a falha
`EmptyReport`, quando não há nada a incluir. 

## API usada pelo Gecert Connect

Estas rotas, também em `/api/keys`, são as que o [Gecert Connect](https://docs.lacunasoftware.com/articles/gecert/gecert-connect#uso-pelas-aplicações) chama em nome do Lacuna Key
Storage Provider. Elas só enxergam as chaves dos certificados a que o usuário autenticado tem acesso, e cada operação com a chave privada
exige a permissão `UseKey` e fica registrada nos usos de chaves. 

| Rota | O que faz |
|---|---|
| `GET /api/keys` | As chaves do usuário: `[{"id": "...", "attributes": {"enabled": true}}]` |
| `GET /api/keys/{id}` | A chave pública: `{"id": "...", "keyType": "RSA", "keyOperations": ["Encrypt", "Decrypt", "Sign", "Verify", "WrapKey", "UnwrapKey"], "rsaModulus": "...", "rsaPublicExponent": "...", "managed": true}`, com o módulo e o expoente em Base64 |
| `POST /api/keys` | Cria uma chave RSA na organização atual. Corpo: `{"keyName": "...", "keyStore": "...", "keySize": 2048, "keyType": "RSA"}`. Exige `ManageKeys` |
| `POST /api/keys/{id}/signature` | Assina um hash. Corpo: `{"algorithm": "RS256", "value": "HASH_EM_BASE64"}`; `algorithm` pode ser `RS256` (padrão) ou `RS512`. Resposta: a assinatura, em Base64 |
| `POST /api/keys/{id}/decryption` | Decripta. Corpo: `{"algorithm": "RSA1_5", "value": "DADO_EM_BASE64"}`; `RSA1_5` (PKCS #1 v1.5) é o único padding e o padrão. Resposta: o dado decriptado, em Base64 |
| `POST /api/keys/{id}/encryption` | Encripta com a chave pública do certificado. Mesmo corpo e resposta |
| `POST /api/keys/{id}/signature-verification` | Verifica uma assinatura com a chave pública. Corpo: `{"algorithm": "RS256", "value": "ASSINATURA_EM_BASE64", "digest": "HASH_EM_BASE64"}`. Resposta: `true` ou `false` |
| `GET /api/keys/stopwatch-info`, `GET /api/keys/{id}/stopwatch-info` | As mesmas respostas de `GET /api/keys` e `GET /api/keys/{id}`, com os tempos gastos em cada etapa (banco de dados, conexão ao repositório, leitura dos parâmetros), usados por **Checar conexão com o servidor** |

Um algoritmo diferente dos aceitos responde com o erro `OperationAlgorithmNotSupported`. 

## Parâmetros de registro de chaves

Para registrar uma chave que já existe no repositório (`PUT /api/keys` ou **Registrar chave existente**), informe os parâmetros que a
identificam, conforme o tipo do repositório. O campo `type` é obrigatório, e `GET /api/key-stores/{type}/example` devolve um modelo.
O GeCert testa os parâmetros antes de salvar: lê a chave pública e assina uma CSR com a chave; se falhar, responde com
`KeyStoreParametersFailedValidation`. 

| Repositório | Parâmetros |
|---|---|
| HSM Kryptus | `{"type": "Kryptus", "publicKeyUniqueIdentifier": "...", "privateKeyUniqueIdentifier": "..."}`: os identificadores únicos KMIP da chave pública e da chave privada |
| Azure Key Vault | `{"type": "AzureKeyVault", "keyName": "..."}` ou `{"type": "AzureKeyVault", "kid": "https://.../keys/nome/versao"}`, com os opcionais `kty` (`RSA`, `RSA-HSM`, `EC` ou `EC-HSM`) e `curveName` |
| Dispositivo PKCS #11 | `{"type": "Pkcs11", "id": "...", "label": "..."}`: o ID da chave (em Base64; na aplicação web, também em hexadecimal) ou o *label* dela. Pelo menos um dos dois |

O repositório no banco de dados não aceita registro de chaves, e todo repositório pode ter o registro desabilitado na
[configuração](https://docs.lacunasoftware.com/articles/gecert/on-premises/configure-key-stores) (`KeyRegistrationDisabled`): nesse caso, o erro é `KeyStoreDoesNotSupportKeyRegistration`.

## Códigos de erro

Os erros têm o formato `{"code": "...", "message": "..."}`, com o código HTTP correspondente. Além dos códigos comuns da plataforma
(`SubscriptionNotFound`, `UserNotFound`, `UploadNotFound`, `RoleMissing` e outros), o GeCert define: 

| Código | Quando acontece |
|---|---|
| `CertificateNotFound`, `GecertKeyNotFound`, `CertificateAccessNotFound`, `KeyStoreAccessNotFound` | O recurso não existe ou não é da organização |
| `SubscriptionMismatch` | A chave informada é de outra organização |
| `BadKeyStore` | O repositório informado não está configurado na instância |
| `BadKeyStoreParameters` | Os parâmetros de registro não puderam ser lidos |
| `KeyStoreParametersFailedValidation` | A chave não pôde ser usada com os parâmetros informados |
| `KeyParametersIncompatibleWithCertificate` | A chave não corresponde ao certificado |
| `KeyStoreDoesNotSupportKeyRegistration` | O repositório não aceita registro de chaves existentes |
| `KeyStoreDoesNotSupportKeyInsertion` | O repositório não aceita a geração nem a importação de chaves (`KeyInsertionDisabled`) |
| `KeyStoreParametersNotAccessible` | Os parâmetros da chave não podem ser exibidos neste repositório |
| `PinProtectionNotSupported` | O repositório não suporta partições |
| `GecertKeyHasActiveCertificate` | A chave não pode ser excluída porque tem um certificado |
| `OperationAlgorithmNotSupported` | O algoritmo da operação não é `RS256`, `RS512` nem `RSA1_5` |
| `GecertConnectServerNotConfigured` | A seção `GecertConnect` do servidor não está preenchida |

## Veja também

* [GeCert](https://docs.lacunasoftware.com/articles/gecert)
* [Gecert Connect](https://docs.lacunasoftware.com/articles/gecert/gecert-connect)
* [Configuração de repositórios de chaves](https://docs.lacunasoftware.com/articles/gecert/on-premises/configure-key-stores)