Authentication

Burl supports HTTP Basic and Bearer authentication. Both populate the Authorization header of the request.

Default Credentials

client::basic_auth and client::bearer_auth set the default Authorization header, sent with every request:

client.basic_auth("user", "pass");
// or client.bearer_auth("a-secret-token");

Per-Request Credentials

The builder offers the same two functions for a single request, overriding any default set on the client:

auto [ec, r] = co_await client.get("https://api.example.com/data")
    .basic_auth("user", "pass")
    // or .bearer_auth("a-secret-token")
    .send();

This is the way to talk to several endpoints with different credentials through one client, or to send one authenticated request from a client that is otherwise anonymous.

Credentials Across Redirects

By default, the Authorization header is dropped when a redirect leads to a different origin than the original request. This prevents credentials intended for one host from being forwarded to another.

When the redirect target is trusted, such as another host in the same service, set config::unrestricted_auth to keep sending it:

burl::client::config cfg;
cfg.unrestricted_auth = true;

burl::client client(co_await capy::this_coro::executor, tls_ctx, cfg);

Credentials are always sent on a redirect that stays on the same origin, regardless of this setting.

Custom Schemes

For an authentication scheme Burl does not build in, you can set the Authorization header yourself with the builder’s header function. A header you set explicitly is sent as-is.

Next Steps

Edit this Page