> 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/hop-api/docs/key-manager.md).
# Key Manager
## Key Manager Generate Key Module
> Returns the KeyId generated by the HSM.
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://api-hext.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"GenerateKeyInput":{"type":"object","required":["client_id","keyName","keySizeType","modeFlag"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyName":{"type":"string","description":"Nome/tipo da chave a ser gerada (ex ZEK, ZPK, ZMK, TMK, BDK)"},"keySizeType":{"type":"string","description":"Tamanho/tipo da chave:\n- S Single DES (64 bits)\n- D Double DES (128 bits)\n- T Triple DES (192 bits)\n- A AES-128\n- B AES-192\n- C AES-256\n"},"modeFlag":{"type":"string","enum":["0","1","A","B"],"description":"Modo de operacao:\n- 0 Gerar chave\n- 1 Gerar chave e exportar sob ZMK/TMK\n- A Derivar chave\n- B Derivar chave e exportar sob ZMK/TMK\n"},"zmk_TMK_flag":{"type":"string","nullable":true,"description":"Flag da ZMK/TMK, obrigatorio quando modeFlag 1 ou B"},"zmk_TMK_keyId":{"type":"string","nullable":true,"description":"Alias da ZMK/TMK, obrigatorio quando modeFlag 1 ou B"},"is_ephemeral":{"type":"boolean","description":"Se true, a chave tera tempo de vida limitado por key_TTL_minutes"},"key_TTL_minutes":{"type":"integer","nullable":true,"description":"Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true"}}},"ReturnImpKey":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","description":"KeyId gerado/importado no banco de dados"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada"},"retKeyTTLmin":{"type":"integer","description":"Tempo de vida da chave em minutos (0 = sem expiracao)"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- 500 Erro interno do servidor\n- 400 Requisicao invalida\n- 155 Chave nao encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descricao do erro"},"retMultiValue":{"nullable":true}}}}},"paths":{"/v4/PayShieldKeyManager/GenerateKey":{"post":{"tags":["Key Manager"],"summary":"Key Manager Generate Key Module","description":"Returns the KeyId generated by the HSM.\n","operationId":"generateKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnImpKey"}}}},"400":{"description":"Requisição inválida — campo obrigatório ausente ou formato incorreto","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## Key Manager Import Key Module
> Returns the KeyId generated from the imported key.
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://api-hext.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ImportKeyInput":{"type":"object","required":["client_id","keyName","keySizeType","key_under_ZMK_to_import","ZMK_keyId"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyName":{"type":"string","description":"Nome/tipo da chave a ser importada (ex ZEK, ZPK, TMK)"},"keySizeType":{"type":"string","description":"Tamanho/tipo da chave:\n- S Single DES\n- D Double DES\n- T Triple DES\n- A AES-128\n- B AES-192\n- C AES-256\n"},"key_under_ZMK_to_import":{"type":"string","description":"Chave criptografada sob a ZMK a ser importada (formato Key Block ou X9.17)"},"ZMK_keyId":{"type":"string","description":"Alias/identificador da ZMK no banco de dados"},"is_ephemeral":{"type":"boolean","description":"Se true, a chave tera tempo de vida limitado por key_TTL_minutes"},"key_TTL_minutes":{"type":"integer","nullable":true,"description":"Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true"}}},"ReturnImpKey":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","description":"KeyId gerado/importado no banco de dados"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada"},"retKeyTTLmin":{"type":"integer","description":"Tempo de vida da chave em minutos (0 = sem expiracao)"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- 500 Erro interno do servidor\n- 400 Requisicao invalida\n- 155 Chave nao encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descricao do erro"},"retMultiValue":{"nullable":true}}}}},"paths":{"/v4/PayShieldKeyManager/ImportKey":{"post":{"tags":["Key Manager"],"summary":"Key Manager Import Key Module","description":"Returns the KeyId generated from the imported key.\n","operationId":"importKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnImpKey"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## POST /v4/PayShieldKeyManager/ImportZMK
> Key Manager Import ZMK Module
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://api-hext.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ImportZMKInput":{"type":"object","required":["client_id","kcv","keyZMK"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"kcv":{"type":"string","minLength":6,"maxLength":6,"description":"Key Check Value da ZMK (exatamente 6 caracteres hexadecimais)"},"keyZMK":{"type":"string","description":"ZMK em formato Key Block Thales"}}},"ReturnImpKey":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","description":"KeyId gerado/importado no banco de dados"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada"},"retKeyTTLmin":{"type":"integer","description":"Tempo de vida da chave em minutos (0 = sem expiracao)"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- 500 Erro interno do servidor\n- 400 Requisicao invalida\n- 155 Chave nao encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descricao do erro"},"retMultiValue":{"nullable":true}}}}},"paths":{"/v4/PayShieldKeyManager/ImportZMK":{"post":{"tags":["Key Manager"],"summary":"Key Manager Import ZMK Module","description":"","operationId":"importZMK","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportZMKInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnImpKey"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## POST /v4/PayShieldKeyManager/ExportKey
> Key Manager Export Key Module
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"tags":[{"name":"Key Manager","description":"Operações de geração, importação, exportação e tradução de chaves criptográficas"}],"servers":[{"url":"https://api-hext.first-tech.net","description":"Homologação (OKE)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via Auth0"}},"schemas":{"ExportKeyInput":{"type":"object","required":["client_id","keyId","ZMK_keyId","export_scheme"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave a ser exportada no banco de dados"},"ZMK_keyId":{"type":"string","description":"Alias/identificador da ZMK sob a qual a chave sera exportada"},"export_scheme":{"type":"string","enum":["X917","TR31","TKBF"],"description":"Esquema de exportacao:\n- X917 Formato X9.17 (apenas DES/3DES)\n- TR31 Formato TR-31 Key Block\n- TKBF Thales Key Block Format\n"}}},"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operacao"}}},"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- 500 Erro interno do servidor\n- 400 Requisicao invalida\n- 155 Chave nao encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descricao do erro"},"retMultiValue":{"nullable":true}}}}},"paths":{"/v4/PayShieldKeyManager/ExportKey":{"post":{"tags":["Key Manager"],"summary":"Key Manager Export Key Module","description":"","operationId":"exportKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportKeyInput"}}}},"responses":{"200":{"description":"Operação realizada com sucesso","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnMultiValue"}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"401":{"description":"Não autorizado — token Bearer ausente ou inválido"},"404":{"description":"Chave não encontrada no banco de dados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnError"}}}}}}}}}
```
## The GenerateKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"GenerateKeyInput":{"type":"object","required":["client_id","keyName","keySizeType","modeFlag"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyName":{"type":"string","description":"Nome/tipo da chave a ser gerada (ex ZEK, ZPK, ZMK, TMK, BDK)"},"keySizeType":{"type":"string","description":"Tamanho/tipo da chave:\n- S Single DES (64 bits)\n- D Double DES (128 bits)\n- T Triple DES (192 bits)\n- A AES-128\n- B AES-192\n- C AES-256\n"},"modeFlag":{"type":"string","enum":["0","1","A","B"],"description":"Modo de operacao:\n- 0 Gerar chave\n- 1 Gerar chave e exportar sob ZMK/TMK\n- A Derivar chave\n- B Derivar chave e exportar sob ZMK/TMK\n"},"zmk_TMK_flag":{"type":"string","nullable":true,"description":"Flag da ZMK/TMK, obrigatorio quando modeFlag 1 ou B"},"zmk_TMK_keyId":{"type":"string","nullable":true,"description":"Alias da ZMK/TMK, obrigatorio quando modeFlag 1 ou B"},"is_ephemeral":{"type":"boolean","description":"Se true, a chave tera tempo de vida limitado por key_TTL_minutes"},"key_TTL_minutes":{"type":"integer","nullable":true,"description":"Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true"}}}}}}
```
## The ImportKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ImportKeyInput":{"type":"object","required":["client_id","keyName","keySizeType","key_under_ZMK_to_import","ZMK_keyId"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyName":{"type":"string","description":"Nome/tipo da chave a ser importada (ex ZEK, ZPK, TMK)"},"keySizeType":{"type":"string","description":"Tamanho/tipo da chave:\n- S Single DES\n- D Double DES\n- T Triple DES\n- A AES-128\n- B AES-192\n- C AES-256\n"},"key_under_ZMK_to_import":{"type":"string","description":"Chave criptografada sob a ZMK a ser importada (formato Key Block ou X9.17)"},"ZMK_keyId":{"type":"string","description":"Alias/identificador da ZMK no banco de dados"},"is_ephemeral":{"type":"boolean","description":"Se true, a chave tera tempo de vida limitado por key_TTL_minutes"},"key_TTL_minutes":{"type":"integer","nullable":true,"description":"Tempo de vida da chave em minutos, obrigatorio quando is_ephemeral true"}}}}}}
```
## The ImportZMKInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ImportZMKInput":{"type":"object","required":["client_id","kcv","keyZMK"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"kcv":{"type":"string","minLength":6,"maxLength":6,"description":"Key Check Value da ZMK (exatamente 6 caracteres hexadecimais)"},"keyZMK":{"type":"string","description":"ZMK em formato Key Block Thales"}}}}}}
```
## The ExportKeyInput object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ExportKeyInput":{"type":"object","required":["client_id","keyId","ZMK_keyId","export_scheme"],"properties":{"client_id":{"type":"integer","format":"int64","minimum":1,"description":"Identificador do cliente"},"keyId":{"type":"string","description":"Alias/identificador da chave a ser exportada no banco de dados"},"ZMK_keyId":{"type":"string","description":"Alias/identificador da ZMK sob a qual a chave sera exportada"},"export_scheme":{"type":"string","enum":["X917","TR31","TKBF"],"description":"Esquema de exportacao:\n- X917 Formato X9.17 (apenas DES/3DES)\n- TR31 Formato TR-31 Key Block\n- TKBF Thales Key Block Format\n"}}}}}}
```
## The ReturnImpKey object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ReturnImpKey":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","description":"KeyId gerado/importado no banco de dados"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com valores adicionais, retMultiValue[0] contem o KCV da chave gerada/importada"},"retKeyTTLmin":{"type":"integer","description":"Tempo de vida da chave em minutos (0 = sem expiracao)"}}}}}}
```
## The ReturnMultiValue object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ReturnMultiValue":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de retorno. 0 = sucesso, outros valores indicam erro"},"retValid":{"type":"boolean","description":"Indica se a operacao foi bem-sucedida"},"retValue":{"type":"string","nullable":true,"description":"Valor de retorno simples"},"retDescription":{"type":"string","description":"Descricao do resultado"},"retMultiValue":{"type":"array","nullable":true,"items":{"type":"string","nullable":true},"description":"Array com os valores de retorno da operacao"}}}}}}
```
## The ReturnError object
```json
{"openapi":"3.0.3","info":{"title":"PayShield Key Manager API","version":"4.1.32"},"components":{"schemas":{"ReturnError":{"type":"object","properties":{"retCode":{"type":"integer","description":"Codigo de erro:\n- 500 Erro interno do servidor\n- 400 Requisicao invalida\n- 155 Chave nao encontrada no banco de dados\n"},"retValid":{"type":"boolean"},"retValue":{"type":"string","nullable":true},"retDescription":{"type":"string","description":"Descricao do erro"},"retMultiValue":{"nullable":true}}}}}}
```
---
# 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/hop-api/docs/key-manager.md?ask=&goal=
```
`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.