Autenticação

Versão da API 2026-10-affable-towhee

Cada chamada à API do Lingara leva um token de acesso. Um servidor obtém um trocando o ID do cliente e o segredo de um cliente OAuth no endpoint de tokens: a concessão client credentials do OAuth 2.0, para um servidor que age em nome próprio. Crie clientes na página Integrações da aplicação web do Lingara, em app.getlingara.com/admin.

Uma sessão ou um cliente

As aplicações do Lingara autenticam-no com uma sessão, que tem todos os âmbitos e gasta a quota do seu plano. Um cliente é mais restrito: escolhe os âmbitos que lhe são permitidos quando o cria, e cada token de acesso que obtém leva apenas os âmbitos que pede.

Três valores

O ID do cliente começa por lgr_cid_ e identifica o cliente no endpoint de tokens. Não é secreto.

O segredo do cliente começa por lgr_cs_ e só é enviado para o endpoint de tokens. É mostrado uma única vez, quando o cria: copie-o nesse momento, porque o Lingara guarda apenas um hash dele.

O token de acesso começa por lgr_at_ e dura uma hora. Vai no cabeçalho Authorization: Bearer das chamadas sob /v1/, e em mais lado nenhum. É o único valor que pertence a esse cabeçalho: um segredo do cliente enviado aí é recusado com 401.

Obter um token de acesso

Envie um formulário com POST para o endpoint de tokens com grant_type=client_credentials. Envie o ID do cliente e o segredo por autenticação HTTP Basic ou como os campos de formulário client_id e client_secret, nunca ambos. scope é uma lista, separada por espaços, de âmbitos permitidos ao cliente; omita-a para obter todos os âmbitos permitidos ao cliente. O comando abaixo pede apenas usage:read, o âmbito de que o exemplo GET /v1/usage mais abaixo precisa.

curl -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read"

A resposta contém access_token, token_type (Bearer), expires_in (3600, em segundos) e scope, os âmbitos que o token tem realmente. Uma troca falhada responde no formato de erro OAuth, {error, error_description}, e não no envelope {code, error} de /v1/. Um segredo errado ou revogado, ou um cliente eliminado, é recusado com 401 e invalid_client. Um âmbito que o cliente não pode pedir faz recusar toda a troca com 400 e invalid_scope; nunca é restringido silenciosamente.

Agir em nome de outro utilizador Lingara

Uma aplicação que age em nome de outro utilizador Lingara usa a concessão por código de autorização. Encaminhe o navegador do utilizador para o URL de autorização com response_type=code, client_id, um redirect_uri que corresponda exatamente a um que registou, scope, state e um code_challenge S256. O utilizador vê a página de consentimento da Lingara e regressa ao seu redirect_uri com code, state e iss. Verifique que state é o que enviou e que iss é https://api.getlingara.com antes de usar o código.

O PKCE é obrigatório

Todos os clientes usam PKCE, apenas com o método S256. Gere um code_verifier aleatório, envie o seu hash SHA-256, codificado em base64url, como code_challenge com code_challenge_method=S256, e guarde o verificador para a troca. Um pedido sem método, ou com plain, é recusado com invalid_request.

Trocar o código

No prazo de 60 segundos, envie com POST para o endpoint de tokens grant_type=authorization_code, code, o mesmo redirect_uri e o code_verifier, autenticando-se como o cliente; um cliente público envia apenas client_id. A resposta acrescenta um refresh_token, que começa por lgr_rt_. O código começa por lgr_ac_ e funciona uma única vez: uma segunda utilização é recusada com invalid_grant e termina os tokens emitidos pela primeira troca.

Renovar

Quando o token de acesso expirar, envie com POST para o endpoint de tokens grant_type=refresh_token e o refresh_token, autenticando-se de novo como o cliente. Cada renovação devolve um novo token de atualização: guarde apenas o mais recente. Faça as renovações uma de cada vez: um token de atualização antigo usado mais de 60 segundos depois de ter sido substituído é considerado roubado e termina os tokens dessa instalação com invalid_grant. Um token de atualização que não seja usado durante 30 dias expira. O endpoint de tokens limita os pedidos por endereço, por isso renove apenas quando um token se esgotar.

As aplicações nativas são clientes públicos

Uma aplicação de computador, móvel ou de linha de comandos não consegue guardar um segredo, por isso é um cliente público: não tem segredo, envia apenas client_id para o endpoint de tokens e regista um redirecionamento de loopback como http://127.0.0.1/callback (qualquer porta) ou um esquema de uso privado como com.example.app:/callback. O utilizador vê a página de consentimento todas as vezes. Uma página web não pode ser um cliente: nem o endpoint de tokens nem /v1/ respondem a um pedido preliminar entre origens.

Quando o utilizador remove a sua aplicação

O utilizador pode remover a sua aplicação a qualquer momento em Aplicações ligadas, ou desinstalando-a se a instalou, e a chamada seguinte dela falha com 401. Quando o utilizador terminar sessão na sua aplicação, revogue o token de atualização dela no endpoint de revogação, o que termina os tokens dessa instalação.

Quando o token expira

Passada uma hora, /v1/ responde 401 com o código unauthorized e um erro que começa por invalid_token. Troque de novo quando uma chamada receber 401, ou pouco antes de expires_in se esgotar, e repita a chamada uma vez. Se a própria troca falhar com invalid_client ou invalid_scope, o cliente ou o seu segredo foi eliminado, revogado ou restringido: pare e corrija-o na página Integrações, porque repetir não pode ter êxito. Guarde o token entre chamadas: o endpoint de tokens limita as trocas por cliente e por endereço, e um programa que troca em cada chamada é recusado com 429 e rate_limited dentro da hora (aguarde Retry-After). Esta concessão não tem token de atualização: o segredo é trocado de novo.

Os tokens de acesso só chegam às rotas da API

Um token de acesso só funciona em rotas sob /v1/. Enviado para qualquer outra rota do Lingara, é recusado com 401, e o corpo começa por api_token_not_accepted, como texto simples ou dentro de um campo error, nunca no envelope {code, error} que as rotas /v1/ usam. Envie o token de acesso no cabeçalho Authorization, como abaixo.

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

Âmbitos

Cada operação precisa de exatamente um âmbito, indicado na sua página. Um token de acesso sem esse âmbito é recusado com 403 e o código insufficient_scope. Para chamar a operação, peça o seu âmbito na troca, se o cliente o tiver permitido. A tabela abaixo lista cada âmbito e as operações que permite.

Quem paga uma chamada

Um cliente é faturado de uma de duas formas, escolhida quando é criado. Um cliente allowance gasta a quota do seu dono, a mesma quota que as suas aplicações, e os seus tokens de acesso também a gastam; GET /v1/usage mostra o que resta. Um cliente metered não gasta quota: é faturado por crédito através de uma subscrição de faturação por utilização que configura na página Integrações. As suas chamadas são recusadas com 402 e spend_cap_reached assim que o cliente ou a sua conta atinge o limite de gastos mensal, e com 402 e metered_billing_inactive enquanto a faturação por utilização não estiver ativa. Um plano de aula vale 10 créditos, uma interação com o tutor 1 crédito e uma geração de vocabulário 3 créditos, pelo que as units indicadas por GET /v1/usage se convertem em créditos com esses pesos. Uma chamada que uma aplicação faz em nome de outro utilizador, com um token obtido a partir de um código de autorização, gasta sempre a quota desse utilizador, seja qual for o modo do cliente.

Mantenha segredos e tokens num servidor

O lugar do segredo do cliente é num servidor que controla, nunca numa página web, numa extensão de navegador ou num pacote de aplicação, onde qualquer pessoa o pode ler. Uma aplicação nativa é um cliente público e não guarda nenhum segredo. Nem /v1/ nem o endpoint de tokens respondem a um pedido preliminar entre origens, pelo que um navegador noutro site não os pode chamar de qualquer forma.

Gerir clientes

Na página Integrações, em app.getlingara.com/admin, crie, mude o nome e elimine clientes, altere o que cada um pode fazer e a versão em que está fixado, e crie e revogue os seus segredos. Eliminar um cliente para de imediato todos os tokens de acesso que ele detém e termina a autorização que cada utilizador lhe concedeu. Revogar um segredo para de imediato todos os tokens de acesso obtidos em troca desse segredo. Restringir os âmbitos de um cliente também se aplica de imediato; alargá-los, ou mudar a sua versão, aplica-se a partir da troca seguinte.

Rodar um segredo

Um cliente pode ter dois segredos ao mesmo tempo. Para rodar, crie um novo segredo, implemente-o e revogue o antigo quando a sua data de «Última utilização» na página Integrações deixar de mudar. Um processo que já tem o novo segredo mas ainda detém um token do antigo recebe um único 401 e troca de novo. O único segredo de um cliente não pode ser revogado: crie primeiro o seu substituto, ou elimine o cliente.

Se uma tradução e a referência em inglês divergirem, prevalece a referência em inglês.