Autenticação e Login
A Carol possui autenticação OAuth, podendo ser explorado a autenticação API Key (também conhecido como API Token ou Connector Token).
→ Veja mais informações sobre OAuth na RFC 6749.
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 | OBRIGATÓRIO. Este parâmetro aceita um dos seguintes valores: password ou refresh_token. Enquanto password é utilizado no fluxo de geração do access token, refresh token é utilizado para renovar tokens já existentes mantendo a sessão ativa, fornecendo tanto um novo access token quanto um novo refresh token. Atenção: Por definição padrão o tempo para expiração de um access token é de uma (01) hora, enquanto de um refresh token é de 72 horas. |
| username | OBRIGATÓRIO. O usuário que está no processo de autenticação. |
| password | OBRIGATÓRIO. A senha do usuário no fluxo de autenticação. |
| refresh_token | OPCIONAL. Obrigatório apenas quando grant_type for refresh_token. Este parâmetro espera o código refresh_token para gerar um novo access token e refresh token. Atenção: Os demais parâmetros devem permanecer vazios. |
| subdomain | OBRIGATÓRIO. Este parâmetro é o nome da Tenant (antes chamado de ambiente). O nome da Tenant é parte da URL, e pode ser obtido da seguinte forma no exemplo a seguir: "totvs.carol.ai/production", o nome da Tenant é production. |
| orgSubdomain | OBRIGATÓRIO. Nome da organização. Este parâmetro espera o mesmo nome definido como subdominio da URL da Carol. Por exemplo, "totvs.carol.ai/production", o nome da organização é totvs. |
| connectorId | OBRIGATÓRIO. Este parâmetro recebe o código do conector ou o nome do conector (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 está válido:
| Parâmetro | Valor |
|---|---|
| access_token | OBRIGATÓRIO. 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" }