jwtpk.mdx

redirect_uri

After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri. The redirect_uri will be called after user authentication for code exchange.

You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios or environments we recommend using the state parameter for the former and multiple projects for the latter.

Auth Request

To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser) on /authorize with at least the following parameters:

• client_id: this tells the authorization server which application it is, copy from Console
• redirect_uri: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
• response_type: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use code
• scope: what scope you want to grant to the access_token / id_token, minimum is openid, if you're unsure what you need you might start with openid profile email

We recommend always using two additional parameters state and nonce. The former enables you to transfer a state through the authentication process. The latter is used to bind the client session with the id_token and to mitigate replay attacks.

You don't need any additional parameter for this request. We're identifying the app by the client_id parameter.

So your request might look like this (linebreaks and whitespace for display reasons):

curl --request GET \
  --url 'https://accounts.zitadel.ch/oauth/v2/authorize
    ?client_id=${client_id}
    &redirect_uri=${redirect_uri}
    &response_type=code
    &scope=openid%20email%20profile'

Additional parameters and customization

There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow. Please check the authorization_endpoint reference in the OAuth / OIDC documentation.

Callback

Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your callback endpoint you provided by the redirect_uri.

:::note If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client, the error will be display directly to the user on the auth server. :::

Upon successful authentication you'll be given a code and if provided the unmodified state parameter. You will need this code in the token request.

If a parameter was missing, malformed or any other error occurred, your answer will contain an error stating the error type, possibly an error_description providing some information about the error and its reason and the state parameter. Check the error response section in the authorization_endpoint reference.

Token request

Next you will have to exchange the given code for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:

• code: the code that was issued from the authorization request
• grant_type: must be authorization_code
• redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request

Depending on your authentication method you'll need additional headers and parameters:

Send a JWT in the client_assertion and set the client_assertion_type to urn:ietf:params:oauth:client-assertion-type:jwt-bearer for us to validate the signature against the registered public key:

curl --request POST \
--url https://api.zitadel.ch/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_assertion=${client_assertion} \
--data client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer