Inicie com nossas APIs REST

As nossas APIs REST efetuam a autenticação via tokens de acesso OAuth 2.0 com o tratamento do retorno dos códigos de resposta HTTP e das mensagens codificadas em JSON. Você pode testar nossas integrações neste portal do desenvolvedor, principalmente, pesquisando APIs na área logada do usuário.

1. Obtenha o ID e segredo de cliente

As integrações da Amil usam um identificador de cliente (client_id) e um segredo de cliente (client_secret) para autenticar chamadas de API:

  • Um ID de cliente é sua identificação no aplicativo (API). Você só precisa de um ID de cliente para obter se tornar um parceiro de vendas do Amil Dental, por exemplo.

  • Um segredo de cliente autentica um ID do cliente, funcionando como uma senha. Para chamar APIs da Amil, você receberá seu token de acesso (access_token) informando ID e segredo do cliente . IMPORTANTE: Mantenha este segredo seguro.

    Veja como obter seu ID e segredo do cliente:

    1. Selecione Entrar na página principal e faça seu login ou cadastre-se;

    2. Selecione a opção "Credenciais de Aplicativo";

    3. Informe os dados solicitados referente ao aplicativo, selecione Criar Aplicativo;

    4. Copie e assegure o armazenamento apropriado do ID do cliente e o segredo para seu aplicativo;

2. Obtenha seu token de acesso

Obtenha seu token de acesso (access_token) usando ID e segredo do cliente. O token de acesso autentica seu aplicativo ao chamar APIs REST da Amil. Você pode chamar a API Amil de Autenticação, usando os exemplos a seguir mostram via cURL ou Postman:

  1. Defina o verbo como POST .

  2. Insira https://api-dev.servicos.grupoamil.com.br/api-autenticacao-apim-test/v2/oauth2/v2.0/token como o URL da solicitação;

  3. Selecione a guia Authorization;

  4. Na lista TIPO, selecione Basic Auth;

  5. No campo Username, insira seu ID de cliente (client_id);

  6. No campo Password, insira o seu segredo (client_secret);

  7. Selecione a guia Body;

  8. Selecione a opção x-www-form-urlencoded;

  9. No campo KEY, insira grant_type;

  10. No campo VALUE, insira client_credentials;

  11. Selecione Enviar;

Exemplo de resposta

Amil retorna um código de acesso (access_token) e o número em segundos que este token é valido.

1 {
2    "access_token": "eyJhbGciOiJSUzI1NoU_ViyPcMJZkWYfuh7oyaUQ4SuDHQ8b86XX0bwAHYO9w0JyL1PxmSHxXb9gACK4agNj48tjLmLqZsdjdJQpwjXXmRMgwqQ0",
3    "token_type": "Bearer",
4    "not_before": 1715899174,
5    "expires_in": 300,
6    "expires_on": 1715899474,
7    "resource": "4ce0f332-b386-4efa-a9cc-e832e676ec9c"
8 }

Efetue chamada em API

Ao chamar uma API, substitua ACCESS-TOKEN por seu código de acesso no header authorization '-H Authorization: Bearer eyHgb(access_token)'. Quando seu código de acesso expirar, chame api-autenticacao-apim-test/v2/oauth2/v2.0/token novamente para solicitar um novo código de acesso.

As formas mais comuns de autenticação

Há um universo de possibilidades no processo de autenticação das API requisitadas. No intuito de descrever uma visão geral sobre o tema, a seguir foram detalhadas algumas das principais opções de autenticação usadas em nosso ecossistema de APIs.

1. Chave de API

O cliente recebe uma chave de acesso gerada por uma sequência de caracteres que somente ele e o serviço de API tomam ciência. Essa a chave é anexada em cada requisição de API. O gateway verifica a chave quando recebe a requisição e garante que o cliente seja autenticado.

O problema dessa abordagem é que, se a chave for extraviada, o invasor poderá usá-la como se fosse um cliente autêntico e realizar todo tipo de operação. Uma forma de mitigar esse risco, é criptografar as requisições usando um protocolo de criptografia como Transport Layer Security (TLS), e com isso a chave não será exposta ao passar pela internet.

2. Nome de usuário e senha

As requisições de API podem usar credenciais básicas como o nome de usuário e senha para autenticação, através de um método chamado autenticação HTTP. Na autenticação HTTP, um nome de usuário e uma senha são codificados e adicionados ao cabeçalho HTTP para todas as requisições de API. O gateway valida essas informações fornecidas numa lista de clientes permitidos.

Como prática moderna, o uso de senhas traz muitos desafios associados, por exemplo, as senhas podem ser perdidas, vazadas, roubadas, adivinhadas ou compartilhadas com partes não confiáveis. Ataques de preenchimento de credenciais e de força bruta podem "quebrar' essas senhas, entre outras formas.

3. Token de OAuth

Um gateway de API pode validar um token de autenticação de um servidor confiável usando o protocolo OAuth, em vez de exigir uma autenticação do cliente. Para usar a API, um usuário faz login em um serviço de terceiros, em vez de efetuar login na API do gateway principal. Assim como ocorre no método de nome de usuário e senha, essa abordagem também é suscetível aos ataques preenchimento de credenciais.

4. TLS mútuo (mTLS)

O TLS é um protocolo de criptografia que estabelece uma conexão criptografada e autenticada entre o cliente e o servidor. Ele também pode verificar e autenticar ambas as extremidades de uma conexão de API. Já no TLS mútuo (mTLS), tanto o cliente quanto o servidor possuem um certificado TLS e se autenticam mutuamente, garantindo que ambos sejam quem alegam ser, sem precisar depender de senhas ou outros métodos de autenticação.

No entanto, a implementação do mTLS também têm seus desafios: todos os clientes e endpoints de API precisam ter certificados TLS legítimos, o que pode ser difícil de aplicar e gerenciar.