API Authentication

Authentication method

The Imara API uses the OAuth 2.0 Client Credentials flow. This is the standard approach for server-to-server communication — your application exchanges a Client ID and Client Secret for a short-lived access token, then includes that token in every API request.

Step 1 — Get your credentials

Before making any API call, you need an API key. Create one in Settings → API Keys. When you create the key, you will receive:

• Client ID — a public identifier for your application
• Client Secret — a private secret (shown once — store it in a secure location immediately)
  
  

Step 2 — Request an access token

Send a POST request to the token endpoint with your credentials encoded as form data:

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

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=openid

A successful response returns a JSON object like this:

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

Step 3 — Call the API

Include the access token in the Authorization header of every request:

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

Token expiry

Access tokens expire after 1 hour (3,600 seconds). When a token expires, API requests will return a 401 Unauthorized response. Simply request a new token using the same Client ID and Secret — there is no refresh token in the client credentials flow.

Best practices

• Cache your token — request a new one only when it expires, not on every API call
• Handle 401 errors gracefully — detect expiry, re-authenticate, and retry the request automatically in your code
• Secure your Client Secret — store it in a secrets manager, never in source code or environment files committed to version control
• Use HTTPS only — never send credentials or tokens over unencrypted connections