A Carol possui autenticação OAuth, podendo ser explorado a autenticação API Key (também conhecido como API Token ou Connector Token).

Índice

Visão Geral

Abaixo um fluxo demonstrando o processo de autenticação OAuth:

Abaixo é listado os principais serviços ligados ao fluxo OAuth:

Esses serviços permitem efetuar a autenticação na Carol e efetuar a validação de um token já existente. Vamos ver os detalhes desses serviços:

/api/v1/oauth2/token

Este endpoint permite efetuar a autenticação na Carol, validando se o usuário e a senha possuem acesso à plataforma. Abaixo é detalhado os parâmetros necessários:

Parâmetro	Valor
grant_type	Este parâmetro aceita um dos seguintes valores: password ou refresh_token. Password é utilizado no fluxo de geração do token, enquanto refresh_token é utilizado par renovar um token já existente.
username	Usuário que esta no processo de autenticação.
password	Senha do usuário no fluxo de autenticação.
refresh_token	Utilizado apenas quando grant_type for refresh_token, este parâmetro espera o refresh_token para gerar umm novo token.
subdomain	Este parâmetro é o nome do ambiente (antes chamado de tenant). O nome do ambiente é parte da URL, e pode ser obetido da seguinte forma: "totvs.carol.ai/production", o nome do ambiente é production.
orgSubdomain	Nome da organização. Este parâmetor espera o mesmo nome definido como subdominio da URL da Carol. Por exemplo, "totvs.carol.ai/production, o nome da organização é "totvs."
connectorId	Este parâmetro recebe o código do conector (connectorID) ou o nome do connector (visualizado na URL ou nos detalhes do conector).

Abaixo é um exemplo da request usando o comando "curl":

curl -X POST "https://clockin.carol.ai/api/v1/oauth2/token" -H "accept: application/json" -H "content-type: application/x-www-form-urlencoded" -d "grant_type=password&connectorId=clockinmobile&username=robson.poffo%40totvs.com&password=SENHA_AQUI&subdomain=clockin&orgSubdomain=global"

O resultado da request é semelhante ao abaixo:

{ "access_token": "1e2fe288fa3a4ca38257294008081317", "client_id": "4c2c9090e7c611e893bf0e900682978b_33dd1190ff2c11e8858be609736e2a59_c1367ca0e86311e8b979aedbc4a09666_mdmConnector", "expires_in": 3495, "refresh_token": "1fd8bc5763734ad0b8e18e2cd328f2f8", "state": "", "timeIssuedInMillis": 1591855130722, "token_type": "bearer" }

/api/v1/oauth2/token/{access_token}/userAccessDetails

Este endpoint permite resgatar detalhes referente ao token, inclusive verificar se o token ainda esta valido:

Parâmetro	Valor
access_token	Access token gerado pelo endpoint "token".

Abaixo é um exemplo da request usando o comando "curl":

 curl -X GET "https://clockin.carol.ai/api/v1/oauth2/token/1e2fe288fa3a4ca38257294008081317/userAccessDetails" -H "accept: application/json"

O resultado da request é semelhante ao abaixo:

{ "envUserId": "c1367ca0e86311e8b979aedbc4a09666", "externalAppId": "33dd1190ff2c11e8858be609736e2a59", "loginLevel": "mdmTenant", "orgId": "856e0510729e11e99928acde48001122", "refreshToken": "1fd8bc5763734ad0b8e18e2cd328f2f8", "system": false, "tenantId": "4c2c9090e7c611e893bf0e900682978b", "userId": "fe115382754247d883d9a11b88b3d96e" }

Connector Token (API Key)

Além do processo convencional de autenticação do processo OAuth, é possível fazer a geracão de um token persistente. Este token é chamado de "Connector Token", e o mesmo é utilizado principalmente em integração de processos sendo que é utilizado uma chave pública e uma chave privada, conforme detalhado a seguir:

Sendo que já efetuamos o login na plataforma, vamos acessar item "Tenant Admin" no menu lateral (primeiro ícone no header, da direita para a esquerda):

Após acessar Tenant Admin, clique na aba "Tokens", a tela abaixo irá aparecer. Nesta tela podemos consultar todos os tokens disponíveis neste ambiente. Lembrando que não é possível ver o token gerado anteriormente - ele está disponível apenas logo após a criação.

A criação de novos tokens ocorre pelo botão "Create token" (na tela acima). Na tela que será aberta, deverá ser selecionado o conector que será utilizado para criar o token, também é possível adicionar uma descrição para revisão futura deste token.

Ao término destes passos a tela abaixo será apresentada. Você deverá guardar as seguintes informações para utilizar nas requests à plataforma:

ConnectorID: 90d7bcd37c424d85a733a42117528792

Connector Token: d0d7dc1612394edcb4d961dc80393cb6

O acesso pelo conector permite visualizar que o conector possui tokens gerados, e é possível navegar para o fluxo acima apresentado (Tenant Admin), podendo assim efetuar a manutenção dos tokens:

Regras de Token

Um item importante a se considerar referente ao Connector é que, em cada tenant, só é possível criar um Token por connector.

Caso o usuário queira efetuar uma consulta se o token ainda é valido, deve-se utilizar o endpoint abaixo, preenchendo o apitoken juntamente com o connector ID:

/api/v1/apikey/details

Revogação

O Connector Token uma vez criado, não se expira. Para que o mesmo seja revogado/invalidado, deve-se por conta das regras abaixo:

1. Revoke Manual: Na lista de Connectores, note que é exibido um connector (referente ao token válido) juntamente com a opção "Revoke". Clicando nesta opção pode-se revogar o token atual.

2. Novo token gerado para o mesmo usuario e conector: Uma vez que um connector já obtém um token criado, caso o usuário crie um novo, o Token anterior será invalidado. Há situações em que outro app pode criar um outro token para o mesmo connector, invalidando o atual. Nesses casos, é recomendado alinhar com o time para que ambos usem o mesmo, evitando impactos de validação.

3. Usuário removido da plataforma.

Próximos Passos

Uma vez que a autenticação ocorreu, teremos o access_token disponível. Este valor deve ser inserido no swagger no atributo "Access Token" (parte superior central).

As subsequentes requests são autenticadas conforme a request a seguir:

 curl -X GET "https://clockin.carol.ai/api/v1/users?pageSize=10&sortOrder=ASC" -H "accept: application/json" -H "Authorization: 1e2fe288fa3a4ca38257294008081317"

Se a autenticação ocorreu através do Connector Token (conforme descrito acima) a request (comando curl) acima ficará da seguinte forma:

curl -X GET "https://clockin.carol.ai/api/v1/users?pageSize=10&sortOrder=ASC" -H "accept: application/json" -H "X-Auth-ConnectorId: 90d7bcd37c424d85a733a42117528792" -H "X-Auth-Key: d0d7dc1612394edcb4d961dc80393cb6"

Árvore de páginas

Autenticação