> For the complete documentation index, see [llms.txt](https://ftcoders.first-tech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ftcoders.first-tech.com/landing-page/modulo-key-manager/arquitetura-autenticacao-e-modelos.md).

# Arquitetura, Autenticação e Modelos

Para consumir o módulo Key Manager de forma segura, a sua aplicação deve seguir os padrões de autenticação da plataforma Hop V4 e respeitar rigorosamente os *schemas* de entrada e saída.

### Arquitetura e Autenticação

#### Base URL e Autenticação Bearer (JWT)

Todas as chamadas para o módulo Key Manager utilizam a seguinte URL base : `https://apivin.first-tech.net/v4/PayShieldKeyManager/`

A autenticação é feita através de um token Bearer (JWT) emitido pelo serviço Auth0. O token deve ser transportado no cabeçalho `Authorization` de todas as requisições :

```http
HTTP
Authorization: Bearer <TOKEN_JWT>
Content-Type: application/json
Accept: */*
```

#### Segregação por `client_id` e `keyId`

* Identificação do Cliente (`client_id`): O `client_id` é o identificador numérico da sua empresa. As chaves ficam fisicamente segregadas por este ID no banco de dados do HSM — ou seja, duas chaves de clientes diferentes nunca interagem .
* Identificador da Chave (`keyId`): As respostas de geração e importação devolverão o alias da chave no campo `retValue`. Este alias deve ser guardado e utilizado nas chamadas futuras. O formato padrão segue a estrutura: `client-{client_id}-key-id-XXX-TIPO`.

### Padrões de Resposta (Envelopes de Saída)

As respostas do módulo Key Manager seguem variações de envelope consoante o endpoint acionado.

#### ReturnImpKey

Utilizado em `GenerateKey`, `ImportKey` e `ImportZMK` (onde é necessário devolver a chave, o KCV e o tempo de vida).

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Descrição Técnica</th></tr></thead><tbody><tr><td><code>retCode</code></td><td><code>integer</code></td><td>Código de retorno. <code>0</code> = sucesso; outros valores = erro (ver catálogo).</td></tr><tr><td><code>retDescription</code></td><td><code>string</code></td><td>Descrição textual do resultado.</td></tr><tr><td><code>retMultiValue</code></td><td><code>string[]</code></td><td><em>Array</em>. A posição <code>[0]</code> contém o KCV (Key Check Value) da chave gerada/importada.</td></tr><tr><td><code>retValid</code></td><td><code>boolean</code></td><td>Indica se a operação global foi bem-sucedida.</td></tr><tr><td><code>retValue</code></td><td><code>string</code></td><td>O <code>keyId</code> gerado/importado no banco de dados (o alias da chave).</td></tr><tr><td><code>retKeyTTLmin</code></td><td><code>integer</code></td><td>Tempo de vida restante da chave em minutos. Retorna <code>0</code> se não tiver expiração.</td></tr></tbody></table>

#### ReturnMultiValue

Utilizado no `ExportKey` (onde a chave criptografada é devolvida no array).

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Descrição Técnica</th></tr></thead><tbody><tr><td><code>retCode</code></td><td><code>integer</code></td><td><code>0</code> = sucesso.</td></tr><tr><td><code>retValue</code></td><td><code>string</code></td><td>Retorna uma <em>string</em> vazia neste endpoint.</td></tr><tr><td><code>retMultiValue</code></td><td><code>string[]</code></td><td><em>Array</em>. A posição <code>[0]</code> contém a chave exportada (encriptada sob a ZMK de destino).</td></tr><tr><td><code>retValid</code></td><td><code>boolean</code></td><td>Indica sucesso.</td></tr><tr><td><code>retDescription</code></td><td><code>string</code></td><td>Descrição textual do resultado.</td></tr></tbody></table>

#### ReturnSingle e ReturnError

* ReturnSingle: Utilizado pelo `TranslateLMK`. A chave re-encriptada sob a LMK atual é devolvida isoladamente na variável `retValue`. O campo `retMultiValue` é `null` .
* ReturnError: Ocorre em respostas HTTP 400, 404 e 500. Mantém a base do `ReturnSingle`, mas com `retValid` em `false`, o código de erro em `retCode` e a mensagem explicativa em `retDescription` .

### Schemas de Entrada (Modelos de Request)

Para simplificar a sua implementação, aqui estão os dicionários de dados exatos que cada endpoint espera receber no seu corpo (`Body`).

#### GenerateKeyInput

Para gerar novas chaves no HSM.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>client_id</code></td><td><code>integer</code></td><td>Sim</td><td>Identificador numérico do cliente.</td></tr><tr><td><code>keyName</code></td><td><code>string</code></td><td>Sim</td><td>Tipo da chave (ex.: <code>ZEK</code>, <code>ZPK</code>, <code>ZMK</code>, <code>BDK</code>).</td></tr><tr><td><code>keySizeType</code></td><td><code>string</code></td><td>Sim</td><td>Tamanho e algoritmo (ex.: <code>S</code>, <code>D</code>, <code>A</code>).</td></tr><tr><td><code>modeFlag</code></td><td><code>string</code></td><td>Sim</td><td>Modo da operação (<code>0</code>, <code>1</code>, <code>A</code>, <code>B</code>).</td></tr><tr><td><code>zmk_TMK_flag</code></td><td><code>string</code></td><td>Condicional</td><td>Obrigatório se <code>modeFlag</code> for <code>1</code> ou <code>B</code>.</td></tr><tr><td><code>zmk_TMK_keyId</code></td><td><code>string</code></td><td>Condicional</td><td>Alias da ZMK/TMK destino. Obrigatório se <code>modeFlag</code> for <code>1</code> ou <code>B</code>.</td></tr><tr><td><code>is_ephemeral</code></td><td><code>boolean</code></td><td>Não</td><td>Se <code>true</code>, define a chave como efémera.</td></tr><tr><td><code>key_TTL_minutes</code></td><td><code>integer</code></td><td>Condicional</td><td>TTL em minutos. Obrigatório se <code>is_ephemeral = true</code>.</td></tr></tbody></table>

#### ImportKeyInput

Para importar uma chave protegida por uma ZMK.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>client_id</code></td><td><code>integer</code></td><td>Sim</td><td>Identificador numérico do cliente.</td></tr><tr><td><code>keyName</code></td><td><code>string</code></td><td>Sim</td><td>Tipo da chave a importar.</td></tr><tr><td><code>keySizeType</code></td><td><code>string</code></td><td>Sim</td><td>Tamanho e algoritmo.</td></tr><tr><td><code>key_under_ZMK_to_import</code></td><td><code>string</code></td><td>Sim</td><td>Chave criptografada sob ZMK (Formato Key Block ou X9.17).</td></tr><tr><td><code>ZMK_keyId</code></td><td><code>string</code></td><td>Sim</td><td>Alias da ZMK base que decifrará o pacote.</td></tr><tr><td><em>(Campos efêmeros)</em></td><td>-</td><td>-</td><td>Aceita <code>is_ephemeral</code> e <code>key_TTL_minutes</code>.</td></tr></tbody></table>

#### ImportZMKInput

Para importar uma ZMK base em formato Key Block.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>client_id</code></td><td><code>integer</code></td><td>Sim</td><td>Identificador numérico do cliente.</td></tr><tr><td><code>kcv</code></td><td><code>string</code></td><td>Sim</td><td>KCV de validação (exatamente 6 caracteres hexadecimais).</td></tr><tr><td><code>keyZMK</code></td><td><code>string</code></td><td>Sim</td><td>A ZMK em formato Key Block Thales puro.</td></tr></tbody></table>

#### ExportKeyInput

Para exportar uma chave para um parceiro.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>client_id</code></td><td><code>integer</code></td><td>Sim</td><td>Identificador numérico do cliente.</td></tr><tr><td><code>keyId</code></td><td><code>string</code></td><td>Sim</td><td>Alias da chave que deseja exportar.</td></tr><tr><td><code>ZMK_keyId</code></td><td><code>string</code></td><td>Sim</td><td>Alias da ZMK que irá encriptar o pacote para envio.</td></tr><tr><td><code>export_scheme</code></td><td><code>string</code></td><td>Sim</td><td>Esquema de exportação (<code>X917</code>, <code>TR31</code>, <code>TKBF</code>).</td></tr></tbody></table>

#### TranslateLMKInput

Para uso em migrações (tradução de LMK).

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Campo</th><th>Tipo</th><th>Obrigatório</th><th>Descrição</th></tr></thead><tbody><tr><td><code>client_id</code></td><td><code>integer</code></td><td>Sim</td><td>Identificador numérico do cliente.</td></tr><tr><td><code>OldKey</code></td><td><code>string</code></td><td>Sim</td><td>Chave Key Block Thales encriptada sob a LMK antiga.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ftcoders.first-tech.com/landing-page/modulo-key-manager/arquitetura-autenticacao-e-modelos.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.