Set the Authorization Header with WinRT HttpClient and OAuth Tokens

You will learn that an OAuth token is normally sent as an HTTP authorization scheme plus a token value, such as Bearer <token>. In WinRT, use HttpCredentialsHeaderValue to construct this typed header value and assign it to DefaultRequestHeaders.Authorization or to one individual request.

An HTTP Authorization header tells a server how the client is authenticating a request. Its usual structure is:

Authorization: <scheme> <credentials>

For an OAuth 2.0 access token, the scheme is commonly Bearer:

Authorization: Bearer eyJhbGciOi...

In WinRT, HttpClient is commonly provided by the Windows.Web.Http namespace. Its headers use WinRT-specific typed classes. The class for the Authorization header is:

Windows.Web.Http.Headers.HttpCredentialsHeaderValue

Credential is not the right type for this job. A credential object generally represents user credentials, such as a username and password, while an OAuth access token is a value placed in a specifically formatted HTTP header.

Using the typed header class is preferable to manually formatting the header because it makes the header's scheme and parameter explicit.

Think of an API request as entering a secure building:

• The Authorization header is the security desk information.
• Bearer is the type of pass you are presenting.
• The OAuth access token is the unique pass number.

The server expects both pieces in the correct order: Bearer followed by the token. Sending only the token is like giving security a pass number without saying what kind of pass it is.

Import the WinRT HTTP namespaces:

using Windows.Web.Http;
using Windows.Web.Http.Headers;

Set an OAuth Bearer token for all requests made by one HttpClient instance:

var httpClient = new HttpClient();
string accessToken = OAuth.token;

httpClient.DefaultRequestHeaders.Authorization =
    new HttpCredentialsHeaderValue("Bearer", accessToken);

This produces a request header equivalent to:

Authorization: Bearer <accessToken>

Then make requests normally:

HttpResponseMessage response = await httpClient.GetAsync(
    new Uri("https://api.example.com/profile"));

The authorization scheme is not always Bearer. Follow the API documentation. For example, an API might require a different scheme:

httpClient.DefaultRequestHeaders.Authorization =
    new HttpCredentialsHeaderValue("Token", accessToken);

For standard OAuth 2.0 access tokens, Bearer is the common choice.

Consider this example:

var client = new HttpClient();
string token = "abc123";

client.DefaultRequestHeaders.Authorization =
    new HttpCredentialsHeaderValue("Bearer", token);

HttpResponseMessage response = await client.GetAsync(
    new Uri("https://api.example.com/orders"));

1. new HttpClient() creates a client that can send HTTP requests.

2. token stores the access token obtained from the OAuth authorization flow.

3. new HttpCredentialsHeaderValue("Bearer", token) creates a structured authorization value with:

   • scheme: Bearer
   • credentials: abc123

4. Assigning it to DefaultRequestHeaders.Authorization makes it a default header for requests sent through client.

5. GetAsync sends a GET request to the orders endpoint.

6. The outgoing request includes:

   Authorization: Bearer abc123
   

7. The server validates the token and either returns the protected resource or responds with an authorization error such as 401 Unauthorized.

OAuth authorization headers are used whenever an application calls a protected API on behalf of a user or application.

• Mobile applications: Send a signed-in user's access token while loading their profile or messages.
• REST API clients: Authenticate calls to endpoints such as /orders, /files, or /calendar/events.
• Background synchronization: Use an application or user token to sync data on a schedule.
• Cloud services: Call services that protect resources with OAuth 2.0 access tokens.
• Desktop applications: Add a token after a login flow before calling the application's backend API.

Use HTTPS for token-bearing requests. An access token can grant access to protected resources, so it must not be exposed over an insecure connection.

In real applications, developers usually avoid scattering header setup across every API call. Instead, they centralize it in an API client or a method that creates authenticated requests.

Set a default header for a short-lived, user-specific client

public HttpClient CreateAuthenticatedClient(string accessToken)
{
    var client = new HttpClient();
    client.DefaultRequestHeaders.Authorization =
        new HttpCredentialsHeaderValue("Bearer", accessToken);

    return client;
}

Set the header on one request

A per-request header is useful when different requests use different tokens or when a client also makes public requests.

var request = new HttpRequestMessage(
    HttpMethod.Get,
    new Uri("https://api.example.com/profile"));

request.Headers.Authorization =
    new HttpCredentialsHeaderValue("Bearer", accessToken);

HttpResponseMessage response = await httpClient.SendRequestAsync(request);

Validate before sending

Use a guard clause so that code does not send an invalid authorization value:

if (string.IsNullOrWhiteSpace(accessToken))
{
    throw new InvalidOperationException("An access token is required.");
}

Handle expired tokens

A 401 Unauthorized response can mean the token is missing, invalid, or expired. Production code commonly refreshes the token through the appropriate OAuth flow, stores the replacement securely, and retries only when it is safe to do so.

Using a nonexistent or incorrect credential type

This does not represent a WinRT authorization header:

// Incorrect for WinRT HttpClient authorization headers
httpClient.DefaultRequestHeaders.Authorization = new Credential(accessToken);

Use HttpCredentialsHeaderValue instead:

httpClient.DefaultRequestHeaders.Authorization =
    new HttpCredentialsHeaderValue("Bearer", accessToken);

Omitting the authorization scheme

This is incomplete for APIs that expect Bearer authentication:

// Incorrect: the server cannot identify the token scheme.
httpClient.DefaultRequestHeaders.TryAppendWithoutValidation(
    "Authorization",
    accessToken);

Include both the scheme and token:

new HttpCredentialsHeaderValue("Bearer", accessToken)

Putting Bearer inside the token parameter

Do not duplicate the scheme:

// Incorrect: becomes "Bearer Bearer abc123"
new HttpCredentialsHeaderValue("Bearer", "Bearer abc123");

Pass only the raw token as the second argument:

new HttpCredentialsHeaderValue("Bearer", "abc123");

Using the wrong API namespace

There are different HttpClient APIs in .NET and WinRT. Make sure the header value class matches the client you use:

• WinRT: Windows.Web.Http.Headers.HttpCredentialsHeaderValue
• Modern .NET: System.Net.Http.Headers.AuthenticationHeaderValue

Logging tokens

Avoid printing authorization headers or full access tokens to logs, crash reports, or the console. Treat access tokens as secrets.

Assuming every authentication method is Bearer

OAuth 2.0 APIs commonly use Bearer, but the server documentation is authoritative. Do not invent the scheme name.

DefaultRequestHeaders are convenient when all requests from a client should have the same authorization. A request-specific header is safer when authorization differs by request.

using Windows.Web.Http;
using Windows.Web.Http.Headers;

Default header for a WinRT client

client.DefaultRequestHeaders.Authorization =
    new HttpCredentialsHeaderValue("Bearer", accessToken);

Header for one WinRT request

request.Headers.Authorization =
    new HttpCredentialsHeaderValue("Bearer", accessToken);

Header sent

Authorization: Bearer <access-token>

Rules

• Use HttpCredentialsHeaderValue with WinRT Windows.Web.Http.HttpClient.
• Use Bearer only when the API specifies Bearer authentication.
• Pass the raw token as the second argument; do not include Bearer twice.
• Use HTTPS.
• Do not log or hard-code real access tokens.
• Handle 401 Unauthorized as a possible missing, invalid, or expired token.

How do I add a Bearer token to a WinRT HttpClient?

Assign a HttpCredentialsHeaderValue to the Authorization header:

client.DefaultRequestHeaders.Authorization =
    new HttpCredentialsHeaderValue("Bearer", accessToken);

What namespace contains HttpCredentialsHeaderValue?

Use:

using Windows.Web.Http.Headers;

It is used with WinRT's Windows.Web.Http.HttpClient.

Is Credential the correct class for an OAuth access token?

No. An OAuth access token is normally sent in an Authorization header with a scheme such as Bearer. In WinRT, represent it with HttpCredentialsHeaderValue.

Should I include Bearer in the token string?

No. Provide Bearer as the first argument and the raw token as the second argument.

new HttpCredentialsHeaderValue("Bearer", accessToken)

Should I use default headers or request headers?

Use DefaultRequestHeaders when every request from that client uses the same token. Set request.Headers.Authorization when only one request needs the token or tokens vary between requests.

What does a 401 response mean after adding the header?

It commonly means the token is missing, invalid, expired, or lacks access to the requested resource. Check the API response and OAuth token lifecycle.

What is the equivalent in modern .NET?

For System.Net.Http.HttpClient, use System.Net.Http.Headers.AuthenticationHeaderValue rather than WinRT's HttpCredentialsHeaderValue.

• OAuth 2.0 access tokens — The token value sent in the Authorization header.
• Bearer authentication — The common authorization scheme used with OAuth access tokens.
• HTTP request headers — The general mechanism for sending request metadata.
• HttpClient — The client object used to create and send HTTP requests.
• HTTP status code 401 Unauthorized — A common response when authentication is missing or invalid.
• HTTP status code 403 Forbidden — Indicates an authenticated caller may lack permission.
• Token refresh — Obtaining a replacement access token when the current one expires.
• HTTPS — Protects tokens while they are transmitted over the network.