SDK Authentication

Purpose

This area describes how the SDK authenticates with the Runtime and what options are available.

Main Capabilities

• API key authentication
• OAuth2 client credentials (machine-to-machine)
• Delegated bearer token (forwarding)

How It Works

The SDK uses a credential provider strategy. The provider is configured once at client construction and enriches every outbound request with the appropriate header. The application code never handles tokens or headers directly.

The Runtime supports two mutually exclusive schemes: a Bearer token in the Authorization header, or an API key in the X-Api-Key header. Bearer is checked first.

API Key

The simplest option. The key is issued from the ApiMapper Portal under a registered client application and is bound to a specific tenant and client ID at issuance time.

The key should be stored in an environment variable or a secret store — never hardcoded.

// .NET
.WithApiKey(configuration["ApiMapper:ApiKey"]);
// or: Environment.GetEnvironmentVariable("APIMAPPER_API_KEY")

// TypeScript
credentials: new ApiKeyCredentialProvider(process.env.APIMAPPER_API_KEY!)

# Python
credentials=ApiKeyCredentialProvider(os.getenv("APIMAPPER_API_KEY"))

// Java
.credentials(new ApiKeyCredentialProvider(System.getenv("APIMAPPER_API_KEY")))

Key rotation: update the environment variable and restart the process. No code change is required.

OAuth2 Client Credentials

Use this when the integrating application has a registered identity in an IdP (Keycloak, Microsoft Entra, Okta, etc.) and the Runtime is configured to trust that IdP.

The SDK fetches a token from the IdP on first use, caches it, and refreshes it automatically before it expires. The application code sees none of this.

// .NET
.WithOAuth2ClientCredentials(opts =>
{
    opts.Authority    = "https://idp.example.com";   // or opts.TokenEndpoint for direct URL
    opts.ClientId     = "sdk-client";
    opts.ClientSecret = configuration["ApiMapper:ClientSecret"];
    opts.Scope        = "apiMapper.runtime";
});

// TypeScript
credentials: new OAuth2ClientCredentialsProvider({
  authority:    "https://idp.example.com",
  clientId:     "sdk-client",
  clientSecret: process.env.APIMAPPER_SECRET!,
  scope:        "apiMapper.runtime",
})

# Python
credentials=OAuth2ClientCredentialsProvider(OAuth2ClientCredentialsOptions(
    authority="https://idp.example.com",
    client_id="sdk-client",
    client_secret=os.getenv("APIMAPPER_SECRET"),
    scope="apiMapper.runtime",
))

// Java
var o = new OAuth2ClientCredentialsProvider.Options();
o.authority    = "https://idp.example.com";
o.clientId     = "sdk-client";
o.clientSecret = System.getenv("APIMAPPER_SECRET");
o.scope        = "apiMapper.runtime";
.credentials(new OAuth2ClientCredentialsProvider(o))

When authority is set, the token endpoint is discovered automatically from {authority}/.well-known/openid-configuration. Set tokenEndpoint directly to skip discovery.

Delegated Bearer Token

Use this when the orchestrator or request pipeline already holds a token for the current user or agent — for example, the incoming HTTP request's JWT. The SDK forwards it without caching or refreshing.

// .NET — forward the token from the current HTTP request
.WithBearerToken(sp =>
{
    var ctx = sp.GetRequiredService<IHttpContextAccessor>().HttpContext;
    return ctx?.GetBearerToken() ?? throw new InvalidOperationException("No token.");
});

// TypeScript — factory called per request
credentials: new DelegatedBearerCredentialProvider(() => getTokenFromContext())

# Python — factory called per request
credentials=DelegatedBearerCredentialProvider(lambda: get_token_from_context())

// Java
.credentials(new DelegatedBearerCredentialProvider(() -> getTokenFromContext()))

Security Notes

The SDK never logs credential values. The clientSecret, Bearer token values, and X-Api-Key values are set only in HTTP headers and are never written to any log output.