---
updatedAt: 2025-09-24T23:45:49.000Z
agentTools:
  projectIndex: https://developer.candis.io/llms.txt
---

# How to Authenticate

This section outlines the process for authenticating a client application (cloud-based or desktop with web server capability) using the Candis Authorization Server.

## 1. Authorization Request

The client application begins by redirecting the resource owner (user) to the Candis Authorization Server for authentication. The redirect url must include:

* The client ID
* The requested scope (Read more about [Token Scopes](https://developer.candis.io/docs/access-token-scopes))
* A redirect URI, where the authorization server will send the user after successful authentication.

> 📘 Note
>
> The redirect URL must be whitelisted in the Candis authentication server. The user should provide their redirect URL to Candis for whitelisting.

**Sample URL**: `https://id.my.candis.io/auth/realms/candis/protocol/openid-connect/auth?client_id=<ClientId>&redirect_uri=<RedirectUrl>&response_type=code&scope=exports core_data offline_access`

## 2. User Authentication and Authorization

* The user authenticates with the Candis Authorization Server by providing their credentials.

<Image alt="Candis Login Page" align="center" width="500px" src="https://files.readme.io/bd2d6ea24db13c215c7ee5d76218b67bd43c249a59a6230cc0704f34b549eed8-image.png">
  Candis Login Page
</Image>

* After successful authentication, the authorization server presents a consent screen to the user, outlining the requested permissions from the client application and prompting the user to select an organization.

<Image alt="Candis Authorization Page" align="center" width="500px" src="https://files.readme.io/fba1ee2ef994697898e3c0aac4507116930c910436c34f8fe0b886b7ffeaec1d-image.png">
  Candis Authorization Page
</Image>

* The user grants authorization to the client application.

## 3. Authorization Code Grant

* Once the user grants authorization, the Candis Authorization Server redirects the user to the client application using the provided redirect URI, along with an authorization code.
* The client application must extract the authorization code from the redirect URI.\
  **Sample URL**: `https://example.com/callback?code=&lt;AuthorizationCode&gt;`
  > 📘 Note
  >
  > The authorization code is a short-lived code that expires within 30 to 50 seconds

## 4. Access Token Request

* The client application sends a request to the Candis Authorization Server to exchange the authorization code for an access token.
* The request must include:
  * The client ID and client secret
  * The redirect URL
  * The authorization code obtained in the previous step.

```shell
# Please verify this script before running, as different systems may handle the syntax differently.

curl --location "https://id.my.candis.io/auth/realms/candis/protocol/openid-connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Authorization: Basic $(echo -n '<ClientId>:<ClientSecret>' | base64)" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=&lt;AuthorizationCode&gt;" \
--data-urlencode "redirect_uri=&lt;RedirectUrl&gt;"
```

> 📘 Info
>
> Please note that the clientId and clientSecret are used for basic authentication, encoded with Base64.

## 5. Access Token Response

* The Candis Authorization Server verifies the client’s credentials and the authorization code.
* Upon successful verification, it issues an access token to the client application.
* The server also provides a refresh token for extended access.

## 6. Accessing Protected Resources

* With the access token, the client application can now make authorized requests to the Candis API on behalf of the user.
* The access token must be included in the request headers to authenticate the client.

<Image alt="Authentication flow" align="center" border={true} src="https://files.readme.io/18da1bcae4c86690c92bc3642f295781e40b7298f354517f15b5d954f791da40-image.png">
  Authentication flow
</Image>

> 📘 Note for Limited Web server Access (e.g., Some Desktop Applications)
>
> * For desktop applications or other clients with limited web server access, the process is slightly different. Instead of redirecting the user to a redirect URI, the authorization server will display the authorization code directly to the user.\
>   ex: [https://my.candis.io/authentication\_code?code=\<AuthenticationCode>](https://my.candis.io/authentication_code?session_state=96e45711-4865-46a4-9da7-fed6c4af40ee\&code=76ca581a-1654-4490-b834-1db6fd1df286.96e45711-4865-46a4-9da7-fed6c4af40ee.263325c4-9309-4a37-9092-33f1b2b19802)
> * In this case, the redirect\_url is <https://my.candis.io/authentication_code>, and this URL should be used as the redirect\_url in [Step 4](https://developer.candis.io/docs/how-to-authenticate#4-access-token-request)
> * The user must manually copy this authorization code and then paste it into the client application.
> * The client application will then use this authorization code to complete the rest of the authentication flow by exchanging it for an access token.