---
title: Configure authentication
summary: Attach bearer, Basic, or NTLM credentials that subsequent requests send to the target endpoint.
status: draft
owner: Framework
last_reviewed: 2026-10-02
library: SAIF.NetCore.HttpClients
reference_type: package
operation_id: OP-02
trigger: A consumer calls BearerToken, SetBasicAuthentication, or SetNtlmAuthentication before issuing requests
---

# Configure authentication

`HttpJsonClient` supports three outbound authentication mechanisms — bearer token, HTTP Basic, and NTLM (explicit credentials or the current process identity) — configured independently and attached automatically to subsequent requests.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-02 |
| **Trigger** | A consumer sets the `BearerToken` property, calls `SetBasicAuthentication`, or calls `SetNtlmAuthentication` on an initialized or uninitialized `HttpJsonClient` |
| **Inputs** | Bearer token string; Basic username/password; NTLM username/password, or none for current identity |
| **Outputs** | An `HttpJsonClient` instance configured to attach the selected credential(s) to outgoing requests |
| **Primary components** | `HttpJsonClient.BearerToken`, `HttpJsonClient.SetBasicAuthentication`, `HttpJsonClient.SetNtlmAuthentication`, `HttpJsonClient.EncodeForBasicAuthentication` |
| **Entry point** | `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClient.cs` |

## Steps

1. **Bearer token**: the consumer sets the `BearerToken` property to a non-empty string. The value is stored on the instance and attached as an `Authorization` header on every subsequent request, regardless of header-persistence settings, because it is a property rather than a `Headers` entry ([BR-HTTP-08](../business-rules.md#br-http-08-bearer-token-header)).
2. **HTTP Basic**: the consumer calls `SetBasicAuthentication(userName, password)`.
   - The method Base64-encodes `userName:password` and adds `Authorization: Basic <encoded>` to the `Headers` dictionary ([BR-HTTP-09](../business-rules.md#br-http-09-basic-authentication-header-encoding)).
   - On failure: if an `Authorization` key already exists in `Headers` — for example because headers were persisted from a previous request — `Headers.Add` throws `ArgumentException` ([BR-HTTP-16](../business-rules.md#br-http-16-duplicate-authorization-key-guard-on-basic-authentication)).
   - If `BearerToken` is also set, both credentials are attached and two `Authorization` header entries are sent on the same request; how the receiving stack resolves the duplicate is unverified**.
3. **NTLM, explicit credentials**: the consumer calls `SetNtlmAuthentication(userName, password)`. The resulting `NtlmAuthenticator` is stored on the instance and assigned to every `RestClient` created for a request ([BR-HTTP-10](../business-rules.md#br-http-10-ntlm-authentication%2C-explicit-or-current-identity)).
4. **NTLM, current identity**: the consumer calls the parameterless `SetNtlmAuthentication()`. RestSharp's `NtlmAuthenticator()` maps to the process's default credentials*, and the resulting authenticator is likewise assigned to every `RestClient` created for a request ([BR-HTTP-10](../business-rules.md#br-http-10-ntlm-authentication%2C-explicit-or-current-identity)).
5. Credential persistence differs by mechanism: the `BearerToken` property and the NTLM authenticator are stored directly on the instance and are never cleared by the library, so they are attached to every subsequent request, including retries, for the instance's lifetime. The Basic `Authorization` header instead lives in the `Headers` dictionary, which is cleared after each request unless `PersistHeadersAfterRequest` is set to `true` ([BR-HTTP-07](../business-rules.md#br-http-07-custom-headers-cleared-after-each-request-unless-persisted)) — so, with default options, Basic authentication must be re-applied with another `SetBasicAuthentication` call before each subsequent request, while bearer and NTLM credentials do not. See [Execute request](execute-request.md) for how each mechanism is attached during request building.

## Process flow

The following diagram visualizes the three independent authentication configuration paths and where each credential is attached.

```mermaid
flowchart TD
    Start([Consumer configures authentication]) --> Choice{Mechanism?}
    Choice -->|Bearer| Bearer["Set BearerToken property"]
    Choice -->|Basic| Basic["SetBasicAuthentication(user, pw)"]
    Choice -->|NTLM explicit| NtlmExp["SetNtlmAuthentication(user, pw)"]
    Choice -->|NTLM current identity| NtlmCur["SetNtlmAuthentication()"]
    Basic --> Exists{"Authorization key<br>already in Headers?"}
    Exists -->|Yes| Throw(["ArgumentException"])
    Exists -->|No| AddHeader["Add Authorization: Basic header"]
    Bearer --> AttachedBearer(["Attached on every request<br>(never cleared)"])
    AddHeader --> AttachedBasic(["Attached only until Headers<br>are cleared after the next request"])
    NtlmExp --> AttachedAuth(["Authenticator assigned<br>to every new RestClient"])
    NtlmCur --> AttachedAuth
```

## Failure and edge-case behavior

- `SetBasicAuthentication` throws `ArgumentException` when called twice on a persisted instance without first removing the existing `Authorization` entry ([BR-HTTP-16](../business-rules.md#br-http-16-duplicate-authorization-key-guard-on-basic-authentication)).
- Combining `BearerToken` with a Basic or custom `Authorization` header produces duplicate `Authorization` header entries on the wire; receiving-side behavior is unverified**.
- No scheme check exists on the base URL, so Basic and bearer credentials can be sent over a plain `http://` endpoint.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Sources
- `src/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/SAIF.NetCore.HttpClients/HttpJsonClient/HttpJsonClient.cs`