Keycloak Id Token vs Access Token

Published
Length
3 min read

Luis Felipe Dias

All posts

In the keycloak id token vs access token split, ID tokens prove who logged in. Access tokens tell a backend service what that user can do. Teams use the ID token inside the client app to read profile data. They send the access token to APIs and backend systems to run actions. Both tokens use JSON format and carry digital signatures from your Keycloak server. Mixing them up can break your app rules or leave backend systems open. How keycloak id token vs access token roles differ Keycloak issue

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

In the keycloak id token vs access token split, ID tokens prove who logged in. Access tokens tell a backend service what that user can do. Teams use the ID token inside the client app to read profile data. They send the access token to APIs and backend systems to run actions. Both tokens use JSON format and carry digital signatures from your Keycloak server. Mixing them up can break your app rules or leave backend systems open.

How keycloak id token vs access token roles differ

Keycloak issues both tokens during an OpenID Connect log in flow. Still, each token has a strict audience and job in your stack. The ID token belongs only to the client app that asked for the login. The app reads this token to get the user name, email, and ID. The app then updates the screen to show that the user is active. You should never send an ID token to an API to ask for data.

The access token is built for the backend service or API you call. It carries scopes, roles, and group names that define what the user can do. The client app does not need to read the inside of an access token. It just attaches the token to the request header when calling a backend service. The backend service checks the token signature, expiration time, and target audience field. If the checks pass, the service runs the request and returns the right data.

How token lifetimes and payloads work in practice

Keycloak lets your team tune what goes inside each token using client scopes. You can map user attributes into the ID token so the frontend stays fast. That way, the app does not need an extra call to fetch profile details. Keep the access token small so network headers stay light on every API call. Only put the specific roles and permissions that the target backend service needs.

Both tokens have short life spans to reduce the risk of stolen keys. When an access token expires, the client app uses a refresh token to get a new one. This happens in the background without making the user log in again. If an admin blocks a user, the refresh step fails right away. Yet valid access tokens still work until their short timer runs out.

Keycloak + Token Rotation: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

Limits of static tokens for backend systems

Tokens work well when your own web apps talk to your own REST APIs. They fall short when engineers need direct sessions with databases, cloud consoles, or internal servers. Most databases and legacy tools do not read Keycloak tokens out of the box. Teams often fall back to shared passwords or static keys for these daily tasks. Static role claims inside a token also cannot control what happens inside a live session.

An access token might let a user reach a database or internal tool. Still, the token alone cannot inspect individual queries or stop a bad delete command. It also cannot mask sensitive fields like emails, phone numbers, card numbers, or national IDs. To close this gap, teams pair Keycloak identity checks with runtime controls at the query level. This setup ties every database query and command back to a single human identity. Data masking then rewrites matched fields in results before they reach the screen.

Add runtime guardrails and masking beside your databases and APIs

Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits beside the service as an open-source proxy, a sidecar for your database or API.

Before a query runs, hoop.dev guardrails check the statement against your rules. An AI Analyzer you configure can score intent or hold risky calls for human review. Next, hoop.dev data masking rewrites sensitive fields in responses, and each verdict is logged per listener. Explore the MIT-licensed project on GitHub.

Frequently asked questions

Can I use a Keycloak ID token to call my backend API?

No, you should never use an ID token to authorize API requests. The ID token only tells the frontend app who logged in. Always send the access token to your backend APIs instead.

Why does my Keycloak access token contain user profile info?

Keycloak adds basic profile claims to both tokens in many standard setups. You can change your client scopes in Keycloak to remove extra profile data from access tokens. This keeps your network requests smaller and cleaner.

How do I check a Keycloak access token in my service?

Your backend service should check the digital signature using the public keys from Keycloak. It must also check that the token has not expired and matches the expected audience. Many standard libraries handle these checks in a few lines of code.

The query runs. The emails stay hidden.