# 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 [#user-delegated-access]

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 [#granting-an-application]

Quando uma política está definida como **Require grant**, autorize uma aplicação a partir do separador **Acesso à aplicação** da API:

1. Escolha **Adicionar aplicação** na secção de acesso delegado pelo utilizador ou na secção de clientes (machine-to-machine).
2. Selecione a aplicação.
3. Selecione os scopes a conceder ou escolha **Grant all permissions** para incluir automaticamente os scopes atuais e futuros.
4. 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](https://dts-identity.com/pt/docs/integrations/applications.md).

[Image: The API list in the Admin Console]

## 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:

1. Selecione uma das aplicações machine-to-machine autorizadas.
2. 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.
3. 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.
4. 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 [#resource-indicators-and-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](https://dts-identity.com/pt/docs/integrations/applications.md#financial-grade-api-security): 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? [#one-api-or-many]

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](#the-api-as-a-verifiable-contract)). 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](#resource-indicators-and-tokens)), e um serviço de backend pode trocar um token que já detém através de [token exchange](#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 [#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](https://dts-identity.com/pt/docs/integrations/applications.md)).
- 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](#user-delegated-access) 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.read
```

A resposta contém o novo `access_token`, juntamente com `expires_in` e o `scope` efetivamente concedido.

## Scopes vs. permissões [#scopes-vs-permissions]

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](#granting-an-application)). 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](#role-based-access-control) 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 [#role-based-access-control]

> **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](https://dts-identity.com/pt/docs/integrations/roles.md).

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](https://dts-identity.com/pt/docs/integrations/roles.md#enforce-on-the-access-token-not-the-id-token).

## A API como contrato verificável [#the-api-as-a-verifiable-contract]

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](https://dts-identity.com/pt/docs/settings/signing-keys.md)).
- 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) [#call-the-management-api-machine-to-machine-quickstart]

Para permitir que um script ou serviço de backend chame a API de gestão da própria plataforma:

1. Crie uma aplicação **machine-to-machine**; consulte [Aplicações](https://dts-identity.com/pt/docs/integrations/applications.md).
2. 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.
3. 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**.
4. Chame os endpoints de gestão em `/api/v1/...` com o token devolvido no cabeçalho `Authorization: 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 [#machine-to-machine-token-limits]

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](https://dts-identity.com/pt/docs/reference/glossary.md).
