Como criar um cliente OAuth

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

Antes de premir «Criar cliente» na página Integrações, decida três coisas: o que o cliente pode fazer, que processo guarda o seu segredo e quem paga as suas chamadas. O guia de Autenticação define as regras; esta página aplica-as a duas empresas fictícias, Luba e Farducks.

Luba: o Dive Deck

A Luba opera submarinos autónomos como serviço de transporte e de boleias partilhadas. O seu Dive Deck mostra a cada passageiro uma frase do mergulho no ecrã da cabina, na língua que está a aprender, e a equipa de operações da Luba acompanha quanto resta da quota.

A Luba cria um único cliente, Luba Dive Deck, com permissão para «Gerar vocabulário» (vocab:generate) e «Ler utilização» (usage:read), faturado a «A quota do seu plano» (allowance). Dois processos partilham-no, e cada um pede na troca apenas o âmbito de que precisa. Uma troca que omita scope obtém todos os âmbitos permitidos ao cliente; uma que peça um âmbito não permitido ao cliente é recusada por inteiro com invalid_scope, nunca restringida em silêncio.

O servidor de despacho escreve as frases de cada mergulho. Pede apenas vocab:generate, pelo que um token que se escape dele não consegue ler a utilização da Luba.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

O painel de operações é um segundo processo do lado do servidor, com o mesmo ID do cliente e o mesmo segredo. Pede apenas usage:read, e lê o que resta da quota.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -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" | jq -r '.access_token // error(.error)')"

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

Ambos os processos correm nos servidores da Luba. O tablet da cabina pede as frases ao servidor de despacho e nunca guarda o segredo nem um token, porque tudo o que está num dispositivo em que um passageiro pode tocar pode ser lido. A secção «Mantenha segredos e tokens num servidor» do guia de Autenticação explica porquê.

O mesmo cliente como um projeto que pode clonar e executar: integrations/luba-dive-deck

Farducks: Batter Rewards

A Farducks é uma cadeia de lojas de conveniência de fish and chips. Enquanto um pedido frita, a aplicação de fidelização Batter Rewards pede ao backend da própria Farducks um plano de aula curto e depois lê-o de volta. A aplicação e as caixas chamam o backend da Farducks, nunca o Lingara, pelo que nenhuma delas guarda o segredo.

A Farducks cria um único cliente, Farducks Batter Rewards, com permissão para «Criar planos de lição» (lesson_plans:write) e «Ler planos de lição» (lesson_plans:read), faturado a «A quota do seu plano» (allowance). É a única faturação com que um cliente pode ser criado hoje, e a faturação de um cliente fica fixada quando é criado. O outro modo, metered («Pagamento por utilização»), é descrito na secção «Quem paga uma chamada» do guia de Autenticação.

O backend pede apenas lesson_plans:write e cria o plano. A resposta é transmitida em fluxo, e o seu evento started traz o plan_id do plano.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/lesson-plans" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context":"Ordering food at a night market","source_lang":"en","target_lang":"zh","level":2}'

Defina ID com esse plan_id, depois peça lesson_plans:read e leia o plano de volta. Uma troca pode pedir vários âmbitos do cliente, separados por espaços em scope; cada comando aqui pede um, porque cada um é composto a partir de uma única chamada.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

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

Um dia, o segredo é colado num pedido de suporte. Na página Integrações, a Farducks prime «Novo segredo» e implementa-o no backend, espera até que a data de «Última utilização» do segredo antigo deixe de mudar e depois prime «Revogar» no segredo antigo. Todos os tokens de acesso obtidos em troca do segredo antigo são recusados a partir desse momento. A secção «Rodar um segredo» do guia de Autenticação indica o limite de dois segredos e porque é que o único segredo de um cliente não pode ser revogado.

O mesmo cliente como um projeto que pode clonar e executar: integrations/farducks-batter-rewards

Próximos passos

O guia de Autenticação aborda os erros da troca, o que fazer quando um token expira e a regra de rotação. O guia de Versões aborda a versão em que um cliente está fixado e como escolher outra para uma única chamada.

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