APIs
Proteja as suas APIs como recursos OAuth: defina scopes, controle o acesso machine-to-machine e de utilizadores e configure tokens.
Uma API representa um recurso protegido para o qual as aplicações obtêm access tokens. Registar uma API indica à plataforma o identificador do recurso (a sua audience), os scopes (permissões) que expõe, as aplicações que a podem chamar e a forma como os access tokens emitidos para ela são estruturados e assinados.
As APIs são geridas em Integrações → APIs na Admin Console.
O que é uma API
Cada API tem:
- um nome: uma designação para administradores, e
- um identificador: o valor de audience que aparece nos tokens emitidos para esta API (por exemplo,
https://api.example.com).
Numa API personalizada, pode também indicar Contactos, os colaboradores a quem pode perguntar sobre ela. São meramente informativos e não recebem quaisquer direitos.
Existem dois tipos:
- System API: a API de gestão da própria plataforma. O nome, o identificador e os scopes são fixos e não podem ser editados.
- Custom API: uma API que regista e governa: define os seus scopes, quem a pode chamar e as definições dos tokens.
Scopes (permissões)
Um scope é uma permissão individual que um token pode transportar, por exemplo read:documents ou orders.write.
- A System API expõe um catálogo fixo de scopes de gestão (por exemplo
users.read,users.write,groups.read,roles.write,logs.read). São estes os scopes que concede às aplicações que chamam a API de gestão da própria plataforma. - Uma Custom API expõe os scopes que o administrador define. No separador de permissões da API, adicione cada scope com um nome e uma descrição. Alguns scopes reservados do OpenID Connect (como
openid,profile,email,offline_access) não podem ser redefinidos.
Alguns scopes de gestão estão deliberadamente ao lado do seu scope base, em vez de estarem implícitos nele. O que importa conhecer é users.mfa.read, que abrange os registos de MFA de um utilizador (que segundos fatores estão registados e quando foi utilizado cada um pela última vez). É necessário em todos os endpoints que devolvem um utilizador, incluindo as respostas das chamadas de criação, atualização, eliminação, desativação e ativação. Um token que detenha apenas users.read ou users.write recebe o utilizador sem a lista de registos, pelo que deve conceder adicionalmente users.mfa.read quando uma integração precisar dela.
Quem pode chamar uma API
Duas políticas independentes controlam o acesso, uma para cada tipo de chamador:
Acesso delegado pelo utilizador
Quando uma aplicação interativa pede um token em nome de um utilizador com sessão iniciada, a user policy da API decide se tal é permitido:
- Allow all: qualquer aplicação interativa pode pedir tokens para esta API.
- Require grant: apenas as aplicações às quais concedeu acesso explicitamente podem pedir tokens, e apenas para os scopes que lhes concedeu.
- Deny all: nenhuma aplicação interativa pode pedir tokens.
Acesso machine-to-machine
Quando uma aplicação se autentica em nome próprio com o grant client-credentials (sem envolvimento de um utilizador), a client policy da API decide se tal é permitido:
- Require grant: apenas as aplicações às quais concedeu acesso explicitamente podem pedir tokens, limitados aos scopes concedidos.
- Deny all: nenhuma aplicação machine-to-machine pode pedir tokens.
Conceder acesso a uma aplicação
Quando uma política está definida como Require grant, autorize uma aplicação a partir do separador Acesso à aplicação da API:
- Escolha Adicionar aplicação na secção de acesso delegado pelo utilizador ou na secção de clientes (machine-to-machine).
- Selecione a aplicação.
- Selecione os scopes a conceder ou escolha Grant all permissions para incluir automaticamente os scopes atuais e futuros.
- Guarde. Os tokens que a plataforma emite para essa aplicação para esta API passam a transportar os scopes concedidos.
Uma aplicação machine-to-machine é normalmente do tipo de aplicação machine-to-machine; consulte Aplicações.

Testar um token de API
Assim que uma API tiver pelo menos uma aplicação machine-to-machine autorizada (com o grant client-credentials), o separador Testar da API permite-lhe experimentar um token de ponta a ponta sem escrever código:
- Selecione uma das aplicações machine-to-machine autorizadas.
- A página mostra um exemplo de pedido de token pronto a executar contra o token endpoint, utilizando o client ID e o secret dessa aplicação e o identificador desta API como audience.
- Mostra a resposta de token e descodifica o access token emitido nas suas partes header, payload e assinatura, para que possa confirmar que a audience e os scopes concedidos são os esperados.
- Mostra um exemplo de chamada à API que envia o token como cabeçalho
Bearer.
Copie os comandos para os executar no seu próprio terminal. Se o separador Testar indicar que tem de autorizar primeiro uma aplicação, conceda acesso a uma aplicação machine-to-machine no separador Acesso à aplicação e recarregue a página.
Resource indicators e tokens
Cada access token que a plataforma emite para uma API transporta o identificador dessa API como audience, para que o recurso possa verificar que o token se destinava a ele. As aplicações selecionam a API para a qual pretendem um token através do resource indicator, o que permite a uma aplicação deter tokens separados, limitados por audience, para várias APIs.
No separador de definições da API, controla a forma como esses tokens são estruturados:
- Algoritmo de assinatura: o algoritmo assimétrico (RS256, RS384, RS512 ou PS256) utilizado para assinar os tokens. Escolha PS256 para uma API chamada por uma aplicação que utilize um perfil de segurança Financial-grade API: esse perfil assina os próprios tokens da aplicação com PS256 e desaconselha RS256. Esta definição é independente do perfil, pelo que tem de ser alterada também aqui.
- Access token lifetime: durante quanto tempo um token é válido (por predefinição, um dia).
- Implicit access token lifetime: uma duração mais curta aplicada aos tokens emitidos através de fluxos implícitos baseados no browser (por predefinição, duas horas).
Uma API ou várias?
Um access token transporta sempre exatamente uma audience. Não são emitidos tokens com várias audiences: um token emitido para uma API não é aceite por outra (consulte A API como contrato verificável). Se o seu backend for um conjunto de microsserviços, isto implica uma decisão de conceção:
Uma API lógica para um domínio de confiança. Registe uma única API cujo identificador represente todo o backend (por exemplo https://api.example.com) e atribua a cada serviço o seu próprio espaço de nomes de scopes (orders.read, inventory.write, etc.). Todos os serviços validam a mesma audience e aplicam apenas os seus próprios scopes; o cliente detém um único token para todo o backend e um novo serviço junta-se acrescentando scopes em vez de um novo registo. Escolha esta opção quando os serviços são desenvolvidos e operados em conjunto, normalmente atrás de um único gateway. Tenha em conta o compromisso: dentro da audience partilhada, os serviços deixam de se isolar mutuamente através da verificação da audience (qualquer um deles aceita um token enviado a um serviço irmão), passando a fazê-lo apenas através dos scopes.
Uma API por fronteira de confiança. Registe APIs separadas quando os recursos têm níveis de confiança ou proprietários diferentes, ou quando há terceiros envolvidos. Um cliente pede então um token separado por API através do resource indicator (consulte Resource indicators e tokens), e um serviço de backend pode trocar um token que já detém através de token exchange. Através da fronteira, a verificação da audience continua a ter significado: um token capturado numa API não tem valor na outra.
É comum combinar ambas: uma API lógica para o núcleo coeso e APIs separadas para as partes que exigem um isolamento mais forte.
Até onde passar o token de um utilizador. Trate o access token do utilizador como uma credencial e não como contexto do pedido. Encaminhe-o no máximo um salto, do cliente até à periferia da sua API (o gateway ou o primeiro serviço). Os serviços mais profundos numa cadeia de chamadas devem estar atrás da audience partilhada da API lógica ou receber um token mais restrito emitido através de token exchange; cada salto adicional que o token original percorre alarga os pontos onde um token comprometido pode ser reutilizado.
Token exchange
O token endpoint suporta OAuth 2.0 Token Exchange (RFC 8693), para que um serviço possa chamar uma API a jusante em nome de um utilizador com sessão iniciada sem reencaminhar o token original: a aplicação troca um access token de utilizador que já detém por um token novo e mais restrito, destinado a outra API.
O grant está deliberadamente limitado a downscoping:
- Só uma aplicação web (confidencial) o pode utilizar, e apenas quando Token exchange estiver ativado entre os seus tipos de grant (consulte Aplicações).
- O subject token tem de ser um access token de utilizador ainda válido, emitido para a mesma aplicação que efetua a troca. Não é suportada a troca de tokens de outra aplicação, de tokens sem utilizador, nem a delegação com um
actor_token. - O pedido indica exatamente uma API de destino através de
resource. A política de acesso delegado pelo utilizador da API de destino aplica-se à aplicação que efetua a troca, como em qualquer outro pedido de token. - O token emitido nunca é mais abrangente do que o subject token: os seus scopes são a interseção dos scopes pedidos, dos scopes do subject token, dos scopes da API de destino e daquilo a que o utilizador tem direito.
- O novo token permanece associado ao mesmo utilizador e à mesma sessão e segue as definições de duração de tokens da API de destino.
Exemplo de pedido ao token endpoint (a aplicação autentica-se da forma habitual, por exemplo com o seu client secret):
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<the user access token>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&resource=https://inventory.example.com
&scope=inventory.readA resposta contém o novo access_token, juntamente com expires_in e o scope efetivamente concedido.
Scopes vs. permissões
Definir um scope numa API apenas o torna passível de ser pedido; não concede acesso a ninguém. O que acaba efetivamente num token é decidido separadamente:
- Nos tokens machine-to-machine, o token transporta exatamente os scopes que o client grant da aplicação autoriza (consulte Conceder acesso a uma aplicação). Um cliente máquina não tem utilizador nem funções, pelo que atribuir uma função a uma aplicação machine-to-machine não tem qualquer efeito: os seus scopes provêm apenas do grant.
- Nos tokens com utilizador (emitidos quando uma aplicação interativa pede um token em nome de um utilizador com sessão iniciada), o controlo de acesso baseado em funções decide a que scopes o utilizador tem direito. Os scopes que acabam no token são a interseção do que a aplicação pediu com aquilo a que o utilizador tem direito.
Esta é a resposta habitual à pergunta "porque é que o scope que pedi falta silenciosamente no meu token?": o scope foi pedido, mas o chamador não tinha direito ao mesmo, pelo que foi descartado em vez de recusado.
Defesa em profundidade: um scope presente num token é uma concessão, não uma garantia. A sua API deve continuar a aplicar as suas próprias verificações ao nível dos objetos (este utilizador é proprietário deste registo?); um token válido com um scope abrangente não substitui a autorização sobre o próprio recurso.
Controlo de acesso baseado em funções
Nota sobre o plano: O controlo de acesso baseado em funções está disponível no plano Advanced e superiores (e no Trial).
Uma Custom API pode optar pelo RBAC, o que permite à plataforma incorporar as funções e permissões de um utilizador diretamente nos tokens que emite para essa API. No separador de definições da API:
- Incluir funções e permissões (RBAC) ativa-o para a API.
- Incluir a claim permissions inclui os scopes concedidos ao utilizador para esta API como claim
permissions. - Incluir a claim roles inclui os nomes das funções do utilizador como claim
roles.
Estas claims só são adicionadas aos tokens com utilizador. A aplicação toma então decisões de autorização com base nessas claims. Para definir funções e atribuí-las a utilizadores e grupos, consulte Funções.
O access token é o local próprio para essas decisões. Uma claim roles também chega ao ID token quando uma aplicação pede o scope roles, mas essa destina-se apenas a apresentação; consulte Aplicar no access token, não no ID token.
A API como contrato verificável
Uma API registada é, na prática, um contrato entre si e o servidor de recursos:
- O seu identificador é estável e torna-se a audience de todos os tokens emitidos para ela.
- A plataforma assina cada token com a sua chave de assinatura (consulte Chaves de assinatura).
- O servidor de recursos valida o token antes de confiar em qualquer scope: verifica a assinatura, que o issuer é esta plataforma e que a audience corresponde ao seu próprio identificador, e só depois lê os scopes.
Se alguma destas verificações falhar, o servidor de recursos deve rejeitar o pedido de imediato.
Chamar a API de gestão (início rápido machine-to-machine)
Para permitir que um script ou serviço de backend chame a API de gestão da própria plataforma:
- Crie uma aplicação machine-to-machine; consulte Aplicações.
- No separador de acesso à aplicação da System API, conceda a essa aplicação os scopes de gestão de que necessita (por exemplo
users.read,groups.write). Conceda apenas os scopes que a integração efetivamente utiliza. - A partir do seu serviço, peça um token com o grant client-credentials ao token endpoint, utilizando o identificador da System API como audience.
- Chame os endpoints de gestão em
/api/v1/...com o token devolvido no cabeçalhoAuthorization: Bearer.
O separador Testar da System API gera exatamente estes dois comandos, pré-preenchidos com uma aplicação real; copie-os como ponto de partida.
Um token deixa de funcionar antes de expirar assim que a aplicação perde o seu acesso na System API, o seu client secret é rodado ou a aplicação é eliminada. O serviço recebe então HTTP 401 e tem de pedir um novo token.
Limites de tokens machine-to-machine
Aplicam-se dois limites aos tokens emitidos através do grant client-credentials. Ambos são apresentados na vista geral Integrações → APIs. Os tokens de inícios de sessão interativos de utilizadores nunca são afetados por nenhum deles.
Pedidos de token por minuto, por cliente: o limite de débito. Os pedidos que o excedam recebem como resposta HTTP 429 e um cabeçalho Retry-After; o cliente pode tentar novamente depois de decorrido o intervalo indicado no cabeçalho.
| Plano | Pedidos de token por minuto |
|---|---|
| Trial | 30 |
| Free | 60 |
| Essential | 1200 |
| Advanced | 6000 |
| Pro | 30 000 |
Tokens por mês, em todo o tenant: um orçamento de volume que só existe nos planos de entrada. Abrange todas as aplicações machine-to-machine e todas as APIs em conjunto e é reposto no dia 1 de cada mês. Quando se esgota, os pedidos client-credentials seguintes recebem como resposta access_denied até ao início do mês seguinte.
| Plano | Tokens por mês |
|---|---|
| Trial / Free | 1000 |
| Essential e superiores | Ilimitado |
Um cliente que guarde em cache o seu access token durante toda a duração do token necessita de cerca de 720 tokens por mês e fica muito abaixo de ambos os limites, pelo que normalmente só um cliente que peça um token novo para cada chamada à API atinge algum deles. Guarde o token em cache no serviço que efetua a chamada e reutilize-o até pouco antes de expirar; a duração do token é configurada por API no separador de definições da API.
Referência para programadores / API
A plataforma inclui documentação de API interativa no produto em /admin/api-docs. Lista todos os endpoints de gestão com os respetivos parâmetros e permite experimentar chamadas no browser; na mesma página pode descarregar a definição OpenAPI legível por máquina.
A API de gestão abrange a administração de utilizadores, grupos, organizações, aplicações, funções, registos e dispositivos. Utilize /admin/api-docs como referência fidedigna dos endpoints, em vez de uma lista estática aqui.
Referência
| Termo | Significado |
|---|---|
| Identificador (audience) | O valor que identifica a API; aparece nos tokens emitidos para ela. |
| Scope / permissão | Uma capacidade individual que um token pode transportar. |
| User policy | Se as aplicações interativas podem obter tokens em nome de um utilizador. |
| Client policy | Se as aplicações podem obter tokens para si próprias (machine-to-machine). |
| Grant | Uma autorização explícita de uma aplicação para chamar esta API com scopes específicos. |
| RBAC | Incorporação das funções e permissões de um utilizador nos tokens da API. |
| Token exchange | Troca de um access token de utilizador por um token mais restrito destinado a outra API (RFC 8693). |
Resolução de problemas
- O pedido de token é rejeitado com um scope inválido. Uma aplicação só pode pedir scopes que lhe tenham sido concedidos na API. Adicione o scope ao grant da aplicação para esta API e peça um token novo.
- As chamadas devolvem um erro de scope insuficiente, apesar de ter sido emitido um token. Um pedido só é bem-sucedido se o token transportar efetivamente o scope exigido pelo endpoint. Descodifique o token e confirme que os scopes concedidos o incluem; os scopes que não foram concedidos à aplicação são descartados silenciosamente do token.
- O token tem a audience errada. O token tem de ser pedido para o identificador (audience) desta API. Um token emitido para outra API, ou sem audience, não é aceite aqui.
- O teste de token não devolve nada ou devolve um erro. O teste emite um token para a aplicação e os scopes selecionados. Certifique-se de que a aplicação tem um grant ativo nesta API e de que está selecionado pelo menos um scope.
- Uma token exchange é rejeitada. O subject token tem de ser um access token com utilizador ainda válido, emitido para a mesma aplicação que efetua a troca; a aplicação tem de ter o grant de token exchange ativado e o pedido tem de indicar exatamente uma API de destino através de
resource. Os tokens machine-to-machine (sem utilizador) não podem ser trocados.
Consulte também o glossário.
Aprovisionamento de aplicações
Crie, atualize e desative contas em aplicações a jusante automaticamente através de SCIM de saída, com mapeamentos de atributos e grupos.
Funções
Agrupar permissões de API em funções e atribuí-las a utilizadores e grupos, para que as aplicações autorizem com base em funções.