> ## Documentation Index > Fetch the complete documentation index at: https://developers.pontua.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Cria uma nova API Key > Gera uma nova chave de API (Bearer Token JWT) para uso em integrações externas. **Importante — token bruto só aparece uma vez:** o token completo retorna apenas no campo `message` deste response. Após esta chamada, o sistema armazena somente o hash. Guarde o token em vault seguro (1Password, AWS Secrets Manager, HashiCorp Vault) imediatamente; ele não pode ser recuperado depois. **Permissões disponíveis (campo `permissions`):** - `read` — leitura (GET) em todos os recursos liberados - `write` — criação (POST) - `update` — atualização (PATCH/PUT) - `delete` — exclusão (DELETE) Conceda **somente as permissões necessárias** (princípio de menor privilégio). Para um bot que só sincroniza frequência num ERP, use `["read"]`. Para uma integração que cria registros de ponto, `["read", "write"]`. **Expiração (`expiresIn`):** 7d, 30d, 45d, 90d, 180d, 1y ou 5y. Default 7d. Chaves expiradas falham com 401. Por boas práticas de segurança, evite 5y exceto em integrações on-premises auditadas. **Auditoria:** o usuário autenticado que criar a chave fica registrado em `createdBy`. Toda chamada feita com o token gera log auditável vinculado a esse usuário. Veja o guia [Autenticação](/conceitos/autenticacao) para o fluxo completo de uso. ## OpenAPI ````yaml https://api.pre.pontua.tech/api/public/doc-json post /api-key openapi: 3.0.0 info: title: Pontua Public API description: >- API oficial da Pontua para integrações de clientes externos. Autentique com o token gerado no dashboard em **Configurações → API**. Envie o token no header `Authorization: Bearer `. version: '1.0' contact: {} servers: [] security: [] tags: [] paths: /api-key: post: tags: - Api Keys summary: Cria uma nova API Key description: >- Gera uma nova chave de API (Bearer Token JWT) para uso em integrações externas. **Importante — token bruto só aparece uma vez:** o token completo retorna apenas no campo `message` deste response. Após esta chamada, o sistema armazena somente o hash. Guarde o token em vault seguro (1Password, AWS Secrets Manager, HashiCorp Vault) imediatamente; ele não pode ser recuperado depois. **Permissões disponíveis (campo `permissions`):** - `read` — leitura (GET) em todos os recursos liberados - `write` — criação (POST) - `update` — atualização (PATCH/PUT) - `delete` — exclusão (DELETE) Conceda **somente as permissões necessárias** (princípio de menor privilégio). Para um bot que só sincroniza frequência num ERP, use `["read"]`. Para uma integração que cria registros de ponto, `["read", "write"]`. **Expiração (`expiresIn`):** 7d, 30d, 45d, 90d, 180d, 1y ou 5y. Default 7d. Chaves expiradas falham com 401. Por boas práticas de segurança, evite 5y exceto em integrações on-premises auditadas. **Auditoria:** o usuário autenticado que criar a chave fica registrado em `createdBy`. Toda chamada feita com o token gera log auditável vinculado a esse usuário. Veja o guia [Autenticação](/conceitos/autenticacao) para o fluxo completo de uso. operationId: ApiKeysController_Create parameters: [] requestBody: required: true description: Nome, permissões e prazo de expiração da chave a ser criada content: application/json: schema: $ref: '#/components/schemas/CreateKeyDto' examples: Chave somente-leitura, 7 dias (ideal para teste/POC): value: name: Pontua Bot — POC integração expiresIn: 7d permissions: - read Chave de leitura + escrita, 1 ano (sync de frequência com ERP): value: name: Sync ERP Domínio - Produção expiresIn: 1y permissions: - read - write Chave full access, 30 dias (operação administrativa de janela curta): value: name: Migração Onboarding Q2 expiresIn: 30d permissions: - read - write - delete - update responses: '201': description: >- Chave criada — o campo `message` contém o token bruto (mostrado apenas aqui) content: application/json: schema: $ref: '#/components/schemas/OkDto' default: description: "\n\t\t\t400 - Bad Request: A solicitação não está no formato correto.\n\t\t\t401 - Unauthorized: A solicitação não foi autorizada. Verifique se o token de acesso é válido.\n\t\t\t403 - Forbidden: Acesso proibido! Requer um nível de permissão mais elevado.\n\t\t\t404 - Not Found: O recurso solicitado não foi encontrado.\n\t\t\t500 - Internal Server Error: Erro de execução no servidor!\n\t\t\t" content: application/json: schema: $ref: '#/components/schemas/ErrorDto' deprecated: false security: - bearer: [] components: schemas: CreateKeyDto: type: object properties: name: type: string description: >- Nome amigável da chave para identificação no inventário. Use algo descritivo do propósito da integração — ex.: "Sync ERP Domínio - Producao", "Bot relatorio mensal contabilidade". example: Sync ERP Domínio - Produção permissions: type: array description: >- Permissões concedidas à chave. Aplique o princípio de menor privilégio — conceda apenas o necessário. `read` = GETs. `write` = POSTs. `update` = PATCH/PUT. `delete` = DELETEs. default: - read example: - read - write items: type: string enum: - read - write - update - delete expiresIn: type: string description: >- Período de validade da chave. Após `expiresAt`, todas as chamadas falham com 401 sem possibilidade de reativação. Para integrações de produção, prefira 1y com rotação automatizada. Evite 5y exceto em ambientes on-premises auditados. default: 7d enum: - 7d - 30d - 45d - 90d - 180d - 1y - 5y example: 1y required: - name - permissions - expiresIn OkDto: type: object properties: status: type: boolean description: Status da operação example: true mensagem: type: string description: Mensagem de retorno example: OK required: - status ErrorDto: type: object properties: service: type: string description: Rota solicitada method: type: string description: Método http message: description: Mensagem do erro oneOf: - type: string example: message erro - type: array items: type: string example: - erro 1 - erro 2 required: - service - method - message ````