Autenticação da API

Método de autenticação

A API da Imara utiliza o fluxo OAuth 2.0 Client Credentials. É a abordagem padrão para comunicação servidor a servidor — sua aplicação troca um Client ID e um Client Secret por um token de acesso de curta duração e inclui esse token em cada requisição.

Passo 1 — Obtenha suas credenciais

Antes de fazer qualquer chamada à API, você precisa de uma chave de API. Crie uma em Configurações → Chaves de API. Ao criar a chave, você receberá:

• Client ID — identificador público da sua aplicação
• Client Secret — segredo privado (exibido uma única vez — armazene-o imediatamente em local seguro)
  
  

Passo 2 — Solicite um token de acesso

Envie uma requisição POST para o endpoint de token com suas credenciais codificadas como dados de formulário:

POST https://auth.imara.com.br/oidc/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=SEU_CLIENT_ID
&client_secret=SEU_CLIENT_SECRET
&scope=openid

Uma resposta bem-sucedida retorna um objeto JSON como este:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Passo 3 — Chame a API

Inclua o token de acesso no cabeçalho Authorization de cada requisição:

GET https://api.imara.com/controls
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Expiração do token

Os tokens expiram após 1 hora (3.600 segundos). Quando um token expira, as requisições retornam 401 Unauthorized. Basta solicitar um novo token com as mesmas credenciais — não há refresh token no fluxo de client credentials.

Boas práticas

• Faça cache do token — solicite um novo apenas quando ele expirar, não a cada chamada
• Trate erros 401 adequadamente — detecte a expiração, reautentique e tente novamente automaticamente
• Proteja o Client Secret — armazene em um gerenciador de segredos, nunca no código-fonte ou em arquivos de ambiente versionados
• Use apenas HTTPS — nunca envie credenciais ou tokens por conexões não criptografadas