Token

Imagine que você criou a loja virtual de uma loja de roupas. Você quer puxar os produtos cadastrados no estúdio de conteúdo e exibi-los no site da loja que o cliente vê. Só que esse site não é uma pessoa, é um programa. Ele não consegue fazer login com usuário e senha como uma pessoa faz. Nesses casos, o token é a chave secreta emitida para que um site ou programa possa acessar o conteúdo no lugar de uma pessoa.

Pense no token como uma única chave que abre uma fechadura. Quem tem essa chave consegue manipular o conteúdo dentro de um escopo definido, sem precisar fazer login. Por isso o token deve ser tratado exatamente como uma senha. Não se deve mostrá-lo a qualquer pessoa, e, se ele vazar, quem o tiver em mãos pode usar essas permissões da mesma forma.

No WEEGLOO existem dois tipos de chave com usos diferentes. Uma é a chave poderosa atrelada à conta (Personal Access Token), e a outra é a chave restrita que serve para ler e entregar conteúdo a um site público (Delivery Access Token). Nesta página, você vê o que é cada uma das duas chaves e quando usá-las, e depois emite cada uma diretamente no estúdio de conteúdo.

As duas chaves têm usos diferentes

Primeiro, veja a diferença entre as duas de uma só vez.

O essencial é o seguinte. O Personal Access Token é mais parecido com uma chave-mestra que substitui uma pessoa, e o Delivery Access Token é uma chave restrita que "só consegue ver o quadro de avisos da entrada". Como os usos não se sobrepõem, basta escolher a chave adequada ao que você quer fazer.

A chave atrelada à conta: Personal Access Token

O Personal Access Token é uma chave que fica atrelada à própria conta que a emitiu. Com essa chave, é possível fazer, sem login, tudo o que essa conta pode fazer no estúdio de conteúdo. Isso inclui tarefas de gerenciamento como cadastrar, editar ou publicar produtos.

Por isso essa chave é poderosa. Por exemplo, se você criar um programa que sobe automaticamente os produtos novos para o estúdio de conteúdo toda noite, esse programa não consegue fazer login como uma pessoa, então você entrega a ele essa chave. É a chave usada para rodar automaticamente tarefas de gerenciamento em lugares que não ficam diretamente à vista das pessoas, como servidores ou scripts de automação.

Por ser poderosa, exige cuidado ao ser manipulada. Essa chave não deve ser colocada no site público que o cliente vê nem no navegador. Se for colocada em um lugar público, qualquer pessoa pode extrair a chave, e quem a obtiver pode usar as permissões da conta que a emitiu da mesma forma. Quando você só vai puxar e exibir produtos em um site público, em vez dessa chave poderosa, use o Delivery Access Token descrito abaixo.

Para emitir o Personal Access Token, basta definir o nome. Você não escolhe um escopo de permissão à parte, porque ele herda exatamente as permissões que a conta que o emitiu possui.

A chave atrelada ao Space: Delivery Access Token

O Delivery Access Token é uma chave somente de leitura atrelada a um único Space específico. Com essa chave, só é possível ler o conteúdo que está em estado Published (publicado) dentro desse Space. O conteúdo em estado Draft que ainda não foi publicado não é lido por essa chave, e também não é possível editar nem excluir nada com ela.

Essa é justamente a chave usada quando o site da loja que o cliente vê puxa e exibe os produtos. O site só precisa exibir os produtos, não precisa cadastrá-los nem apagá-los, então uma chave restrita que só consegue ler já é suficiente. Mesmo que essa chave vaze, apenas o conteúdo publicado é lido, e não é possível danificar o conteúdo.

O que significa publicar (Published) um conteúdo e por que é preciso publicar para que ele fique disponível externamente (entregue) é tratado em Estados e publicação.

Atrele um papel restrito para limitar o que pode ser lido

Ao emitir um Delivery Access Token, você define até onde essa chave pode ler por meio de um SpaceRole (papel) e o atrela junto. Um papel é um conjunto de permissões que define "o que pode ser feito e até qual ação". Quando você atrela um papel à chave, ela só consegue ler até onde o papel atrelado permite.

No caso do site da loja, basta ler os "produtos", então você cria e atrela um papel restrito que permite apenas Read sobre os produtos (Content). Assim, mesmo que essa chave vaze, apenas as informações dos produtos são lidas, sem que outro conteúdo ou informações de membros vazem.

Não atrele o papel Administrator, que pode manipular tudo. O Administrator é o papel de permissão máxima, capaz de manipular tudo dentro desse Space. Atrelar uma permissão tão ampla a uma chave de site público que só precisa ler aumenta o risco quando a chave vaza. O mais seguro é criar à parte um papel restrito que leia apenas o necessário e atrelá-lo.

Como criar um papel e restringir suas permissões é tratado em Papéis e permissões. Veja essa página e prepare com antecedência o papel que permite apenas Read de produtos, para atrelar à chave do site público.

Cuidando do valor secreto emitido

Para as duas chaves, ao concluir a emissão, o valor secreto do token aparece na tela. Esse valor é a própria chave. É ele que você usa ao colocá-la em um servidor ou site. Copie e guarde o valor ali mesmo, logo após a emissão. Você também pode conferi-lo novamente na tela de detalhes do token.

Mas as duas chaves ficam em lugares diferentes.

• Trate o Personal Access Token como uma senha. Por ser uma chave poderosa, mantenha-a apenas dentro do servidor e não a coloque no site público que o cliente vê, no navegador nem em código que outras pessoas possam ver.
• O Delivery Access Token, ao contrário, tem como finalidade original ser colocado no site público que o cliente vê. Na prática, qualquer pessoa que abrir o site pode ver esse valor, mas, como você atrelou um papel restrito, mesmo que alguém pegue esse valor não consegue fazer nada além do escopo de leitura que o papel permite. Por isso, colocá-lo no site em si não é um problema. Apenas não o espalhe à toa para fora do site onde você pretende usá-lo.

Se você perder uma chave ou achar que ela foi usada de forma diferente da pretendida, basta apagar essa chave, emitir uma nova e fazer a substituição.

Emitir um Personal Access Token

Vamos emitir o Personal Access Token que será entregue ao programa que sobe automaticamente os produtos novos toda noite.

1. Nas configurações da conta, abra a tela de Personal Access Token.
2. Pressione o botão Criar no canto superior direito.
3. No campo de nome, digite Upload noturno de produtos novos. Esse nome serve para você reconhecer depois para que fim a chave foi criada.
4. Pressione o botão Guardar para emitir.

Quando a emissão termina, o valor secreto do token aparece na tela. Copie-o ali mesmo e guarde-o em um lugar seguro. O formato da tela é igual ao resultado da emissão do Delivery Access Token abaixo.

Emitir um Delivery Access Token

Desta vez, vamos emitir o Delivery Access Token que o site da loja vai usar ao puxar e exibir os produtos. Essa chave fica atrelada ao Space da loja de roupas, e você atrela junto um papel restrito que consegue ler os produtos.

Primeiro, é preciso que exista no Space o papel que será atrelado a essa chave. Prepare com antecedência, em Papéis e permissões, um papel que permita apenas Read sobre os produtos (Content). A seguir, vamos supor que esse papel foi criado com o nome Somente leitura de produtos.

1. Nas configurações do Space da loja de roupas, abra a tela de Delivery Access Token.
2. Pressione o botão Criar no canto superior direito.
3. No campo de nome, digite Entrega para o site da loja.
4. No campo de descrição, você pode anotar onde essa chave é usada. (É opcional.)
5. Em Space Role, escolha Somente leitura de produtos. Não escolha Administrator.
6. Pressione o botão Criar para emitir.

Quando a emissão termina, o valor secreto do token aparece na tela. Copie-o ali mesmo e guarde-o em um lugar seguro.

Apague as chaves que você não usa mais

É mais seguro apagar as chaves que deixaram de ser usadas, em vez de deixá-las como estão. Encontre na lista de tokens a chave que você não usa mais e apague-a. Quando você apaga uma chave, não é mais possível acessar nada com ela. O mesmo vale quando você acha que uma chave vazou. Basta apagar a chave suspeita, emitir uma nova e fazer a substituição.

O que fazer a seguir

• Papéis e permissões: crie o papel com escopo de leitura restrito para atrelar ao Delivery Access Token.
• Estados e publicação: o que é lido com o Delivery Access Token é apenas o conteúdo em estado Published. Entenda o que é publicar.
• Referência da API: trata de especificações técnicas, como o formato das requisições necessárias para emitir tokens ou puxar conteúdo diretamente a partir de um programa.