Skip to main content

Authentication (C# SDK)

  • Last updated
  • View as Markdown

The Market Data API uses a Bearer Token for authentication. The token is required for almost every request. Your token should have been e-mailed to you when you first signed up for an account. If you do not have a token or have lost your sign-up email, request a new token from the Market Data Dashboard.

There are four ways to set your token when using the C#/.NET SDK, in increasing order of precedence:

  1. Store it in .NET user secrets (recommended for local development)
  2. Load it from a .env file in the working directory
  3. Set it from an environment variable (recommended for production; highest precedence of the automatic sources)
  4. Pass it directly through MarketDataClientOptions when creating the client

When you create a client without explicit options, the SDK loads MARKETDATA_TOKEN (and every other MARKETDATA_* setting) from user secrets, then the .env file, then environment variables — later sources override earlier ones. Explicit options bypass that cascade entirely.

tip

When your code is running in a production environment, we recommend using an environment variable or a managed secret store to ensure your token is not stored with your code. This is the most secure way to set your token.

How To Set Up The Environment Variable​

Set The Environment Variable In The Console​

This command sets the environment variable for the current session only. If you open a new terminal or restart your computer, it will not persist.

export MARKETDATA_TOKEN="your_api_token"

Make The Variable Persistent​

Add the export line to your shell's profile script (~/.zshrc, ~/.bashrc, ~/.bash_profile, etc.), then restart your terminal or run source ~/.zshrc (adjusting for your shell).

Using .NET User Secrets​

For local development, user secrets keep the token out of your project directory entirely. From your executable project's directory:

dotnet user-secrets init
dotnet user-secrets set "MARKETDATA_TOKEN" "your_api_token"

The SDK reads user secrets automatically when you create a client without explicit options.

Using a .env File​

The SDK also loads a .env file from your working directory at startup. Create a file named .env in your project root:

.env
MARKETDATA_TOKEN=your_api_token
warning

Add .env to your .gitignore so the token is not committed to source control.

Make A Test Request​

Verify your authentication is working by making a test request against SPY (or any symbol that requires authentication). Do not use AAPL to test authentication — AAPL is a free test symbol and returns data even when you are not authenticated.

using MarketDataApp;
using MarketDataApp.Exceptions;

try
{
    // No need to pass a token here — the SDK reads MARKETDATA_TOKEN automatically,
    // and CreateAsync validates it against the API before returning the client.
    using var client = await MarketDataClient.CreateAsync();
    var quote = (await client.Stocks.GetQuoteAsync("SPY")).Values[0];
    Console.WriteLine(quote);   // SPY mid=642.18 last=642.05
}
catch (AuthenticationException e)
{
    Console.WriteLine($"Authentication failed: {e.Message}");
}

Passing the Token Directly​

If you prefer to pass the token explicitly (not recommended for production code), set ApiToken on MarketDataClientOptions. Explicit options replace the automatic cascade, so nothing is read from the environment:

using MarketDataApp;

var options = new MarketDataClientOptions
{
    ApiToken = Environment.GetEnvironmentVariable("MY_APP_MARKETDATA_TOKEN")
};

using var client = await MarketDataClient.CreateAsync(options);

Startup Token Validation​

When a token is configured, the client validates it at startup by default — on both construction paths. The startup GET /user/:

  1. fails fast on an invalid token by throwing AuthenticationException, and
  2. seeds the client-wide rate-limit snapshot (client.LatestRateLimit) from the x-api-ratelimit-* response headers before your first data request.

In asynchronous applications, prefer the async factory, which runs the validation without blocking the calling thread:

using var client = await MarketDataClient.CreateAsync(options);

The plain constructor runs the same validation as a blocking request, which makes it the fail-fast choice for synchronous hosts and dependency-injection factories that cannot await:

// Validates the token with a blocking GET /user/ when a token is configured.
using var client = new MarketDataClient(options);

Startup validation is governed by MarketDataClientOptions.ValidateTokenOnStartup. Set it to false for first-request (lazy) validation with no startup network I/O:

var options = new MarketDataClientOptions { ValidateTokenOnStartup = false };
Demo mode

If no token is found anywhere in the cascade, the SDK runs in demo mode — startup validation is skipped and you can call the free, public endpoints (such as AAPL quotes and client.Utilities.GetStatusAsync()). Authenticated endpoints throw AuthenticationException on first use.

Next Steps​

After successful authentication, read the overview of how the client works, then configure Settings to customize output format, date format, and other universal parameters.