Authentication and authorization in Ktor Client

Ktor provides the Auth plugin to handle authentication and authorization in your client application. Typical usage scenarios include logging in users and gaining access to specific resources.

Supported authentication types

HTTP provides a general framework for access control and authentication. The Ktor client allows you to use the following HTTP authentication schemes:

Basic - uses Base64 encoding to provide a username and password. Generally is not recommended if not used in combination with HTTPS.
Digest - an authentication method that communicates user credentials in an encrypted form by applying a hash function to the username and password.
Bearer - an authentication scheme that involves security tokens called bearer tokens. For example, you can use this scheme as a part of OAuth flow to authorize users of your application by using external providers, such as Google, Facebook, Twitter, and so on.

Add dependencies

To enable authentication, you need to include the ktor-client-auth artifact in the build script:

implementation("io.ktor:ktor-client-auth:$ktor_version")

implementation "io.ktor:ktor-client-auth:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-client-auth-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

You can learn more about artifacts required by the Ktor client from Adding client dependencies.

Install Auth

To install the Auth plugin, pass it to the install() function inside a client configuration block:

import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.auth.*
//...
val client = HttpClient(CIO) {
    install(Auth) {
        // Configure authentication
    }
}

Now you can configure the required authentication provider.

Configure authentication

Step 1: Choose an authentication provider

To use a specific authentication provider (basic, digest, or bearer), you need to call the corresponding function inside the install {} block. For example, to use the basic authentication, call the basic {} function:

install(Auth) {
    basic {
        // Configure basic authentication
    }
}

Inside the block, you can configure settings specific to this provider.

Step 2: (Optional) Configure the realm

Optionally, you can configure the realm using the realm property:

install(Auth) {
    basic {
        realm = "Access to the '/' path"
        // ...
    }
}

You can create several providers with different realms to access different resources:

install(Auth) {
    basic {
        realm = "Access to the '/' path"
        // ...
    }
    basic {
        realm = "Access to the '/admin' path"
        // ...
    }
}

In this case, the client chooses the necessary provider based on the WWW-Authenticate response header, which contains the realm.

Step 3: Configure a provider

To learn how to configure settings for a specific provider, see a corresponding topic:

Token caching and cache control

The Basic and Bearer authentication providers maintain an internal credential or token cache. This cache allows the client to reuse previously loaded authentication data instead of reloading it for each request, improving performance while still allowing full control when credentials change.

Accessing authentication providers

When the authentication state needs to be updated dynamically during the client session, you can access a specific provider using the authProvider extension:

val provider = client.authProvider<BearerAuthProvider>()

To retrieve all installed providers, use the authProviders property:

val providers = client.authProviders

These utilities allow you to inspect providers or clear cached tokens programmatically.

Clearing cached tokens

To clear cached credentials for a single provider, use the clearToken() function:

val provider = client.authProvider<BasicAuthProvider>()
provider?.clearToken()

To clear cached tokens across all authentication providers that support cache clearing, use the clearAuthTokens() function:

client.clearAuthTokens()

Clearing cached tokens is typically used in the following scenarios:

When the user logs out.
When credentials or tokens stored by your application change.
When you need to force providers to reload the authentication state on the next request.

Here's an example for clearing cached tokens when the user logs out:

fun logout() {
    client.clearAuthTokens()
    storage.deleteCredentials()
}

Controlling caching behavior

Both Basic and Bearer authentication providers allow you to control whether tokens or credentials are cached between requests using the cacheTokens option.

For example, you can disable caching when credentials are dynamically provided:

basic {
    cacheTokens = false   // Reloads credentials for every request
    credentials {
        loadCurrentCredentials()
    }
}

Disabling token caching is especially useful when authentication data changes frequently or must reflect the most recent state.

19 December 2025