Identifying user in backend

AwillSoftwares · 2025-12-10T10:12:46.350Z

its considered ok to write the session id and sessionToken of user in a cookie and identify the user calling {zitadelApi}/v2/sessions/{sessionId}?sessionToken={tokenId} ?

A

Ask Inkeep•12/10/25, 10:12 AM

Hi @AwillSoftwares, I'm an AI assistant for ZITADEL. While a team member reviews this question, I'll see if I can find relevant sources for your question.

A

Ask Inkeep•12/10/25, 10:13 AM

Answer

Yes, storing the

sessionId

sessionId

and

sessionToken

sessionToken

sessionToken

sessionToken in a cookie to identify users is a valid approach when building a custom login UI with the Session API. (1)

The session token can be used to authenticate against ZITADEL APIs and retrieve session/user information. (2)

However, a few important notes:

Session tokens are opaque, not OIDC-compliant — they require you to interpret them yourself. If you need standard OIDC tokens (id_token, access_token) , you'll need to implement the OIDC flow after session creation. (3)
The session token updates on each session modification — always use the token from the most recent response, as previous tokens are invalidated. (4)
For logout, you can terminate the session by providing the session token in the request body. (1)

If you need standard access/refresh tokens for your application, consider completing the OIDC authorization flow using the session (via the Create Callback endpoint) rather than relying solely on session tokens. (1)

A

Ask Inkeep•12/10/25, 10:15 AM

To learn more, see the sources I considered:

[1] Register and Login User with Password in a Custom Login UI
[2] Create Session
[3] Choose organization on login
[4] Set Session

A

Ask Inkeep•12/10/25, 10:15 AM

Feel free to tag @Ask Inkeep with additional questions.

A

AwillSoftwaresOP•12/10/25, 10:16 AM

how to get oicd tokens from my backend?

A

AwillSoftwaresOP•12/10/25, 10:16 AM

@Ask Inkeep how to get oicd tokens from my backend?

A

Ask Inkeep•12/10/25, 10:16 AM

Thanks for the follow-up, @AwillSoftwares. I'll get back to you soon.

A

Ask Inkeep•12/10/25, 10:17 AM

Answer

To get OIDC tokens from your backend after authenticating a user via the Session API, you need to finalize the auth request by linking your session to the OIDC flow. (1)

Flow overview:

Your application initiates an OIDC authorization request to ZITADEL
After authenticating the user (creating/updating a session) , finalize the auth request by sending the session token to the callback endpoint
ZITADEL returns a callback URL containing the authorization code
Exchange the code for tokens at the token endpoint (2)

Finalize the auth request:

curl --request POST \
 --url ${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546 \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer '"$TOKEN"''\
 --header 'Content-Type: application/json' \
 --data '{
 "session": {
 "sessionId": "225307381909694508",
 "sessionToken": "7N5kQCvC4jIf2OuBjwfyWSX2FUKbQqg4iG3uWT-TBngMhlS9miGUwpyUaN0HJ8OcbSzk4QHZy_Bvvv"
 }
}'

curl --request POST \
 --url ${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546 \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer '"$TOKEN"''\
 --header 'Content-Type: application/json' \
 --data '{
 "session": {
 "sessionId": "225307381909694508",
 "sessionToken": "7N5kQCvC4jIf2OuBjwfyWSX2FUKbQqg4iG3uWT-TBngMhlS9miGUwpyUaN0HJ8OcbSzk4QHZy_Bvvv"
 }
}'

curl --request POST \
 --url ${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546 \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer '"$TOKEN"''\
 --header 'Content-Type: application/json' \
 --data '{
 "session": {
 "sessionId": "225307381909694508",
 "sessionToken": "7N5kQCvC4jIf2OuBjwfyWSX2FUKbQqg4iG3uWT-TBngMhlS9miGUwpyUaN0HJ8OcbSzk4QHZy_Bvvv"
 }
}'

curl --request POST \
 --url ${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546 \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer '"$TOKEN"''\
 --header 'Content-Type: application/json' \
 --data '{
 "session": {
 "sessionId": "225307381909694508",
 "sessionToken": "7N5kQCvC4jIf2OuBjwfyWSX2FUKbQqg4iG3uWT-TBngMhlS9miGUwpyUaN0HJ8OcbSzk4QHZy_Bvvv"
 }
}'

(1)

Exchange the code for tokens (using PKCE) :

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri} \
--data client_id=${client_id} \
--data code_verifier=${code_verifier}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri} \
--data client_id=${client_id} \
--data code_verifier=${code_verifier}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri} \
--data client_id=${client_id} \
--data code_verifier=${code_verifier}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri} \
--data client_id=${client_id} \
--data code_verifier=${code_verifier}

A

Ask Inkeep•12/10/25, 10:17 AM

(2)

The token endpoint will return an

access_token

access_token

,

id_token

id_token

, and optionally a

refresh_token

refresh_token

refresh_token

refresh_token.

Key requirement: The authorization header for finalizing the auth request must be from an account with the

IAM_LOGIN_CLIENT

IAM_LOGIN_CLIENT

role. (1)

A

Ask Inkeep•12/10/25, 10:17 AM

To learn more, see the sources I considered:

[1] Support for the OpenID Connect(OIDC) Standard in a Custom Login UI
[2] Authenticate users with OpenID Connect

A

Ask Inkeep•12/10/25, 10:17 AM

Feel free to tag @Ask Inkeep with additional questions.

A

AwillSoftwaresOP•12/10/25, 10:18 AM

@Ask Inkeep its from my backend, do i really need pkce?

A

Ask Inkeep•12/10/25, 10:18 AM

Thanks for the follow-up, @AwillSoftwares. I'll get back to you soon.

A

Ask Inkeep•12/10/25, 10:18 AM

Answer

No, PKCE is not strictly required for a confidential backend (server-side) application. (1)

For confidential clients (Web applications) , you have multiple authentication options: (2)

Client Secret Basic – Send
```
client_id
```
client_id
```
client_id
```
client_id
and
```
client_secret
```
client_secret
```
client_secret
```
client_secret
as a Basic Auth header
Client Secret POST – Send credentials in the request body
Private Key JWT – Use a signed JWT for authentication

Example token exchange with Client Secret Basic:

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

PKCE is recommended as the default for all client types because it protects against authorization code interception attacks. (1) However, since your backend can securely store a client secret, you can use client secret authentication instead.

For machine-to-machine scenarios (no user interaction) , the recommended approach is JWT bearer token with private key.

A

Ask Inkeep•12/10/25, 10:18 AM

To learn more, see the sources I considered:

[1] Recommended authorization flows with OpenID Connect (OIDC) and OAuth 2.x
[2] Authenticate users with OpenID Connect

A

Ask Inkeep•12/10/25, 10:18 AM

Feel free to tag @Ask Inkeep with additional questions.

A

AwillSoftwaresOP•12/10/25, 10:35 AM

@Ask Inkeep curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

{"error":"invalid_request","error_description":"client_id or client_assertion must be provided"}

A

Ask Inkeep•12/10/25, 10:35 AM

Thanks for the follow-up, @AwillSoftwares. I'll get back to you soon.

A

Ask Inkeep•12/10/25, 10:35 AM

Answer

The error indicates that even with Basic Auth, you still need to include the

client_id

client_id

client_id

client_id. For client_secret_post authentication, you should send both

client_id

client_id

client_id

client_id and

client_secret

client_secret

client_secret

client_secret as parameters in the body: (1)

curl --request POST \
 --url ${CUSTOM_DOMAIN}/oauth/v2/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=authorization_code \
 --data code=${code} \
 --data redirect_uri=${redirect_uri} \
 --data client_id=${CLIENT_ID} \
 --data client_secret=${CLIENT_SECRET}

curl --request POST \
 --url ${CUSTOM_DOMAIN}/oauth/v2/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=authorization_code \
 --data code=${code} \
 --data redirect_uri=${redirect_uri} \
 --data client_id=${CLIENT_ID} \
 --data client_secret=${CLIENT_SECRET}

curl --request POST \
 --url ${CUSTOM_DOMAIN}/oauth/v2/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=authorization_code \
 --data code=${code} \
 --data redirect_uri=${redirect_uri} \
 --data client_id=${CLIENT_ID} \
 --data client_secret=${CLIENT_SECRET}

curl --request POST \
 --url ${CUSTOM_DOMAIN}/oauth/v2/token \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --data grant_type=authorization_code \
 --data code=${code} \
 --data redirect_uri=${redirect_uri} \
 --data client_id=${CLIENT_ID} \
 --data client_secret=${CLIENT_SECRET}

Alternatively, if you want to use client_secret_basic (Basic Auth header) , make sure the Basic Auth header is correctly constructed. The header should be

Basic base64(client_id:client_secret)

Basic base64(client_id:client_secret)

Basic base64(client_id:client_secret)

Basic base64(client_id:client_secret) .

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

curl --request POST \
--url ${CUSTOM_DOMAIN}/oauth/v2/token \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ${BASIC_AUTH}' \
--data grant_type=authorization_code \
--data code=${code} \
--data redirect_uri=${redirect_uri}

(2)

Double-check that

${BASIC_AUTH}

${BASIC_AUTH}

${BASIC_AUTH}

${BASIC_AUTH} is the base64-encoded string of

client_id:client_secret

client_id:client_secret

client_id:client_secret

client_id:client_secret. If the Basic Auth header isn't being parsed correctly, ZITADEL will fall back to requiring

client_id

client_id

client_id

client_id in the body.

A

Ask Inkeep•12/10/25, 10:36 AM

To learn more, see the sources I considered:

[1] OpenID Connect Endpoints in ZITADEL
[2] Authenticate users with OpenID Connect

A

Ask Inkeep•12/10/25, 10:36 AM

Feel free to tag @Ask Inkeep with additional questions.

A

AwillSoftwaresOP•12/10/25, 10:38 AM

@Ask Inkeep what is the code of --data code=${code} \

A

Ask Inkeep•12/10/25, 10:38 AM

Thanks for the follow-up, @AwillSoftwares. I'll get back to you soon.

A

Ask Inkeep•12/10/25, 10:39 AM

Answer

The

code

code

in

--data code=${code}

--data code=${code}

--data code=${code}

--data code=${code} is the authorization code that was issued from the authorization request. (1)

In the OIDC authorization code flow:

After the user authenticates, ZITADEL redirects the user's browser to your
```
redirect_uri
```
redirect_uri
```
redirect_uri
```
redirect_uri
(callback endpoint)
This callback includes a
```
code
```
```
code
```
parameter in the URL
You extract this
```
code
```
```
code
```
and use it in the token request (2)

As stated in the documentation: "Upon successful authentication you'll be given a

code

code

and if provided the unmodified

state

state

parameter. You will need this

code

code

in the token request."

Since you're using the Session API with a custom login UI, you get this authorization code by finalizing the auth request via the Create Callback endpoint — ZITADEL returns a callback URL containing the authorization code, which you then extract and use in the token exchange.

A

Ask Inkeep•12/10/25, 10:39 AM

To learn more, see the sources I considered:

[1] OpenID Connect Endpoints in ZITADEL
[2] Authenticate users with OpenID Connect

A

Ask Inkeep•12/10/25, 10:39 AM

Feel free to tag @Ask Inkeep with additional questions.

A

AwillSoftwaresOP•12/10/25, 10:40 AM

@Ask Inkeep what is this number in ${CUSTOM_DOMAIN}/v2/oidc/auth_requests/V2_224908753244265546

A

Ask Inkeep•12/10/25, 10:40 AM

Thanks for the follow-up, @AwillSoftwares. I'll get back to you soon.

A

Ask Inkeep•12/10/25, 10:41 AM

Answer

The

V2_224908753244265546

V2_224908753244265546

V2_224908753244265546

V2_224908753244265546 is the authRequestId — the unique identifier of the authorization request. (1) (2)

How you obtain it:

When your application initiates an OIDC authorization request (e.g., redirecting to

/oauth/v2/authorize

/oauth/v2/authorize

/oauth/v2/authorize

/oauth/v2/authorize) , ZITADEL creates an auth request and redirects to your login UI with this ID in the URL. You extract it from that redirect URL.

What it represents:

The

authRequestId

authRequestId

authRequestId

authRequestId identifies the specific OIDC flow in progress. You use it to:

Get auth request details — retrieve the
```
clientId
```
```
clientId
```
,
```
scope
```
scope
```
scope
```
scope
,
```
redirectUri
```
redirectUri
```
redirectUri
```
redirectUri
, etc.:

curl --request GET \
 --url <https://$%7BCUSTOM_DOMAIN%7D/v2/oidc/auth_requests/V2_224908753244265546> \
 --header 'Authorization: Bearer '"$TOKEN"''

curl --request GET \
 --url <https://$%7BCUSTOM_DOMAIN%7D/v2/oidc/auth_requests/V2_224908753244265546> \
 --header 'Authorization: Bearer '"$TOKEN"''

curl --request GET \
 --url <https://$%7BCUSTOM_DOMAIN%7D/v2/oidc/auth_requests/V2_224908753244265546> \
 --header 'Authorization: Bearer '"$TOKEN"''

curl --request GET \
 --url <https://$%7BCUSTOM_DOMAIN%7D/v2/oidc/auth_requests/V2_224908753244265546> \
 --header 'Authorization: Bearer '"$TOKEN"''

(1)

Finalize the auth request — link your authenticated session to the OIDC flow to get the authorization code

The

V2_

V2_

V2_

V2_ prefix indicates it's from the v2 API. (3)

A

Ask Inkeep•12/10/25, 10:41 AM

To learn more, see the sources I considered:

[1] Support for the OpenID Connect(OIDC) Standard in a Custom Login UI
[2] Get Auth Request

A

Ask Inkeep•12/10/25, 10:41 AM

Feel free to tag @Ask Inkeep with additional questions.