> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Documentação sobre Token # CREATE TOKEN Cria um token para o usuário atual: o servidor gera um Secret aleatório, adiciona-o ao usuário atual como um [método de autenticação](/pt-BR/reference/statements/create/user#identification) adicional e o retorna como resultado da consulta. O Secret é exibido somente por esta consulta — ele é armazenado com hash, portanto não pode ser recuperado posteriormente. Sintaxe: ```sql theme={null} CREATE TOKEN [{VALID UNTIL datetime | VALID FOR interval}] [GRANTS (privilege ON object [,...])] ``` Esta é uma forma abreviada de `ALTER USER ADD IDENTIFIED WITH sha256_password BY ''` com as mesmas cláusulas [`VALID UNTIL`](/pt-BR/reference/statements/create/user#valid-until-clause) e [`GRANTS`](/pt-BR/reference/statements/create/user#grants-clause), de modo que um token se comporta como uma senha comum do usuário atual: * está vinculado ao usuário — é exibido em `system.query_log` e `system.processes` como o usuário, deixa de funcionar quando o usuário é excluído e perde os direitos de acesso quando o usuário os perde; * pode ser limitado no tempo com `VALID UNTIL` ou `VALID FOR`, e nos privilégios com `GRANTS`; * pode ser usado com qualquer mecanismo de autenticação que aceite uma senha, por exemplo, o parâmetro `password` da interface HTTP ou a opção `--password` do `clickhouse-client`. Criar um token exige o privilégio `CREATE TOKEN` ou o privilégio `ALTER USER` sobre o usuário atual. Trata-se de um privilégio separado porque um token reduz o nível de segurança da conta à qual pertence: um usuário autenticado com uma chave de hardware ou um certificado pode usá-lo para criar uma senha de longa duração para essa mesma conta. O mesmo privilégio autoriza a instrução equivalente `ALTER USER ADD IDENTIFIED ...`. ## Resultado A consulta retorna uma linha com duas colunas: | Coluna | Tipo | Descrição | | - | - | - | | `token` | `String` | O Secret gerado. | | `valid_until` | `DateTime64(0)` | Quando o token expira. `0` significa que ele nunca expira, seguindo a mesma codificação da coluna `valid_until` de [`system.users`](/pt-BR/reference/system-tables/users). | Para obter o Secret sem qualquer formatação, selecione-o com `FORMAT TSVRaw`: ```sql theme={null} CREATE TOKEN VALID FOR INTERVAL 30 DAY GRANTS (SELECT ON db.*) FORMAT TSVRaw ``` O Secret tem 32 caracteres e é gerado a partir de uma fonte aleatória criptograficamente segura, portanto não precisa ser (e não é) validado contra as [regras de complexidade de senha](/pt-BR/reference/statements/create/user#identification) — elas existem para restringir senhas escolhidas por pessoas. ## Cláusulas VALID UNTIL e VALID FOR Limitam o ciclo de vida do token. Funcionam exatamente como as cláusulas correspondentes de um método de autenticação de [`CREATE USER`](/pt-BR/reference/statements/create/user#valid-until-clause): `VALID UNTIL` recebe uma data e hora absolutas; `VALID FOR` recebe um [interval](/pt-BR/reference/data-types/special-data-types/interval) que é somado ao horário atual no momento em que a consulta é executada. Sem nenhuma dessas cláusulas, o token permanece válido por [`create_token_default_ttl_seconds`](/pt-BR/reference/settings/session-settings/create), que é de 30 minutos por padrão; ou seja, um token para o qual não se solicita uma duração maior tem vida curta. Defina essa configuração como `0` ou escreva `VALID UNTIL 'infinity'` para criar um token que nunca expira. Exemplos: * `CREATE TOKEN VALID UNTIL '2026-12-31'` * `CREATE TOKEN VALID FOR INTERVAL 30 DAY` * `CREATE TOKEN VALID UNTIL 'infinity'` ## Cláusula GRANTS Limita os direitos de acesso das sessões autenticadas com o token à interseção com os privilégios listados. Funciona exatamente como a [cláusula `GRANTS` de `CREATE USER`](/pt-BR/reference/statements/create/user#grants-clause), incluindo suas limitações — notadamente, o limite é aplicado no nó que recebe a consulta e não é propagado para os demais nós de um cluster. A cláusula nunca adiciona direitos de acesso: um privilégio que não tenha sido concedido ao usuário permanece indisponível para o token. Sem a cláusula, o token possui todos os direitos de acesso do usuário. Exemplos: * `CREATE TOKEN GRANTS (SELECT ON db.table)` * `CREATE TOKEN VALID FOR INTERVAL 90 DAY GRANTS (SELECT ON db.table, INSERT ON db.table)` Nem esse limite nem o limite de tempo se aplicam ao que as sessões do token deixam para trás — consulte [Considerações de segurança](#security-considerations). ## Gerenciando tokens Um token é um método de autenticação do usuário, portanto é listado por [`SHOW CREATE USER`](/pt-BR/reference/statements/show#show-create-user) (com suas cláusulas `VALID UNTIL` e `GRANTS`, mas sem o Secret) e nas colunas `auth_type`, `auth_params` e `auth_grants` da tabela [`system.users`](/pt-BR/reference/system-tables/users). Não há nenhuma instrução que remova um único token. Para revogar todos os tokens de um usuário, substitua seus métodos de autenticação, por exemplo com `ALTER USER IDENTIFIED WITH ...`, ou use `ALTER USER RESET AUTHENTICATION METHODS TO NEW` para manter apenas o mais recente. O número de métodos de autenticação que um usuário pode ter ao mesmo tempo é limitado pela configuração do servidor `max_authentication_methods_per_user`. O Secret é gerado e armazenado pela própria consulta; assim, um `CREATE TOKEN` cujo resultado nunca chega ao cliente — uma conexão perdida enquanto a linha está sendo enviada, ou um `INTO OUTFILE` que o cliente não consegue abrir — deixa para trás um método de autenticação que ninguém pode usar e que, mesmo assim, conta para esse limite. Ninguém detém esse Secret: ele existe apenas enquanto a consulta é executada. Já uma consulta rejeitada antes de ser executada, inclusive aquela cuja cláusula `FORMAT` indica um format que não pode ser usado, não adiciona nada. `CREATE TOKEN` não oferece suporte à cláusula `ON CLUSTER`. Use um armazenamento de acesso replicado (ou execute a consulta em cada nó com a instrução equivalente `ALTER USER ... ADD IDENTIFIED WITH sha256_hash`) para que um token funcione em um cluster cujas access entities são armazenadas localmente. ## Considerações de segurança `VALID UNTIL` e `GRANTS` restringem as sessões que se autenticam com o token. Eles não restringem o que essas sessões deixam para trás: * O prazo é verificado no momento em que uma sessão se autentica com o token. Uma sessão já aberta, e uma consulta já em execução, não são interrompidas quando o token expira. * Tudo o que uma sessão cria sobrevive ao token, e um objeto que executa trabalho por conta própria continua executando-o: uma [view materializada atualizável](/pt-BR/reference/statements/create/view#refreshable-materialized-view) continua se atualizando, uma visão materializada anexada a um motor de tabela de streaming como [`Kafka`](/pt-BR/reference/engines/table-engines/integrations/kafka), [`RabbitMQ`](/pt-BR/reference/engines/table-engines/integrations/rabbitmq), [`NATS`](/pt-BR/reference/engines/table-engines/integrations/nats) ou [`S3Queue`](/pt-BR/reference/engines/table-engines/integrations/s3queue) continua consumindo, e um dicionário com [`LIFETIME`](/pt-BR/reference/statements/create/dictionary/lifetime) continua recarregando, muito depois de o token ter expirado. Uma visão realiza esse trabalho com os direitos de seu [`DEFINER`](/pt-BR/reference/statements/create/view#sql_security), que por padrão é o usuário que criou a visão — todos os direitos do usuário, e não apenas os direitos a que a cláusula `GRANTS` do token o limitou. Um token com permissão para criar tabelas, visões ou dicionários pode, portanto, ampliar na prática os seus dois limites: ele pode deixar para trás uma tarefa persistente que continua em execução após o prazo e faz, com os direitos do usuário, aquilo que o próprio token não tinha permissão para fazer. Conceda a um token apenas o que a aplicação precisa — geralmente `SELECT` e `INSERT` em tabelas nomeadas — e mantenha `CREATE TABLE`, `CREATE VIEW`, `CREATE DICTIONARY` e os privilégios `ACCESS MANAGEMENT` fora de sua cláusula `GRANTS` sempre que os limites precisarem valer de fato. Uma sessão autenticada com um token que possui uma cláusula `GRANTS` não pode emitir tokens de forma alguma: adicionar um método de autenticação a um usuário existente é negado para esse tipo de sessão. A cláusula `GRANTS` de um novo método de autenticação é cruzada, no login, com os direitos de acesso do usuário, e não com os da sessão que criou o método; caso contrário, isso seria uma forma de ampliar o limite.