Skip to main content

Authentication

The @Auth annotation configures authentication for requests.

No authentication (default)​

@GET("/public/data")
@Returns(Data::class)
@Serializable
object GetPublicDataRequest

Bearer token authentication​

@GET("/secure/data")
@Auth(type = AuthType.BEARER)
@Returns(Data::class)
@Serializable
object GetSecureDataRequest

Generated method requires a token context parameter:

context(token: String)
suspend fun getSecureData(): ApiResponse<Data>

Usage:

context("my-bearer-token") {
    client.getSecureData()
}

Basic authentication​

@GET("/protected/resource")
@Auth(type = AuthType.BASIC)
@Returns(Resource::class)
@Serializable
object GetProtectedResourceRequest

Generated method requires username and password context parameters:

context(username: String, password: String)
suspend fun getProtectedResource(): ApiResponse<Resource>

Usage:

context("admin", "secret") {
    client.getProtectedResource()
}

API key authentication​

@GET("/api/data")
@Auth(type = AuthType.API_KEY)
@Returns(Data::class)
@Serializable
object GetApiDataRequest

By default, the processor uses the X-API-Key header name, but you can customize it:

@GET("/api/data")
@Auth(type = AuthType.API_KEY, headerName = "X-Custom-API-Key")
@Returns(Data::class)
@Serializable
object GetApiDataRequest

Generated method requires an apiKey context parameter:

context(apiKey: String)
suspend fun getApiData(): ApiResponse<Data>

Usage:

context("my-api-key") {
    client.getApiData()
}

Custom authentication​

@GET("/custom/auth")
@Auth(type = AuthType.CUSTOM)
@Returns(Data::class)
@Serializable
object GetCustomAuthDataRequest

Generated method signature:

context(customAuth: HttpRequestBuilder.() -> Unit)
suspend fun getCustomAuthData(): ApiResponse<Data>

Usage:

context({ headers.append("X-Custom-Header", "value") }) {
    client.getCustomAuthData()
}