Core call context

A type that holds values that apply only to a single method call to the Hive Axyl server. It specifies the idempotency key, additional headers, the timeout and retry policy, credentials, and the cancellation token.

ApiCallContext is always the last parameter, and you can omit it. If you omit it, the default values apply, so you do not need to specify it for most calls. Add-on methods that wrap native features take a CancellationToken as the last parameter instead of a call context.

Create a new instance for each call, and do not share it between threads.

ApiCallContext

class — namespace Hive.Axyl.Core

Pass it to methods that call the Hive Axyl server.

Properties

Property	Type	Description
`IdempotencyKey`	`string?`	The key used for idempotent processing. A UUIDv4 is filled in by default on creation, and the value stays the same even when the transport layer retries. If the request is not idempotent, set it to `null`.
`Metadata`	`Dictionary<string, string>`	Custom headers to send additionally with the request. Setting it to `null` throws `ArgumentNullException`.
`Policy`	RequestOptions?	The policy that applies only to this call. If `null`, the global default values of `CoreConfig` are used.
`Credential`	CallCredential	The credentials this call uses. The default value is `Ambient`, which uses the current session.
`Token`	`CancellationToken`	The token used to cancel the call.

The idempotency key is sent as the Idempotency-Key header only for methods that the server requires it for. It is set once per logical call, and the value does not change even when the transport layer retries.

Headers you cannot put in Metadata

The following items are not sent, and a warning is logged.

Header names that the SDK fills in itself, such as Authorization, X-App-Id, and traceparent
Header names that are not in the RFC 7230 token format
Values that are empty or contain control characters or non-ASCII characters

When names overlap, the value the SDK fills in always takes precedence.

WithAccessToken

Creates a context that authenticates the call with the specified access token instead of the current session. This is the same as setting CallCredential.Bearer() in Credential.

Use it in the automatic login flow, where you check that a saved token is still valid and then confirm it as the session.

Unity

static ApiCallContext WithAccessToken(string accessToken)

Parameter	Type	Required	Description
`accessToken`	`string`	Required	The access token to use for this call.

Returns: ApiCallContext

No exception is thrown even if the token is null or empty. The call fails with InvalidArgument before it reaches the network, so you can pass a value read from storage as is without checking it.

Call example

Unity

using Hive.Axyl.Core;

var result = await auth.LoginWithAccessTokenAsync(
    request,
    ApiCallContext.WithAccessToken(storedAccessToken));

For when to use it, see Automatic login.

RequestOptions

class — namespace Hive.Axyl.Core

Set it in ApiCallContext.Policy to apply a different policy to this call only. Properties that are null use the global default values of CoreConfig.

The range of values is not checked. The caller must take care not to pass invalid values such as negative numbers.

Property	Type	Description
`TimeoutMillis`	`int?`	The timeout for this request, in milliseconds.
`MaxRetries`	`int?`	The maximum number of retries for this request.
`IsIdempotent`	`bool`	If `true`, the request is treated as idempotent regardless of the HTTP method and is retried on transient failures.
`SkipLogging`	`bool`	If `true`, request and response logging is skipped.

Credentials are not a policy. Specify which credentials to call with in ApiCallContext.Credential.

CallCredential

struct — namespace Hive.Axyl.Core

The credentials a single call uses. The type and the token are bound into one value, so "which credentials" and "which token" can never mismatch.

Credential types

There are three types of credentials.

Ambient: The default value, which authenticates with the current session
Anonymous: A value that sends no credentials
Bearer(): A value that authenticates with the specified access token

Check which type the current value is with IsAmbient, IsAnonymous, and IsBearer. ToString() does not output the token and shows it only in the form Bearer(***).

Ambient

Authenticates with the SDK's current session. The session's Authorization header is attached, automatic token refresh runs when a 401 response is received, and if a refresh is in progress, the call waits behind it.

This is the same as not specifying Credential. Explicitly setting Ambient on a method declared as not requiring authentication does not turn it into an authenticated call.

Unity

static CallCredential Ambient { get; }

Anonymous

Sends no credentials. The Authorization header is not attached, a 401 response does not trigger automatic refresh, and the call neither waits for nor fails because of an in-progress refresh.

This is the value the SDK applies automatically to methods declared as not requiring authentication.

Unity

static CallCredential Anonymous { get; }

Bearer

Authenticates with the specified access token instead of the current session. Use it when you check that a saved token is valid and then confirm it as the session.

It does not participate in automatic refresh. A 401 response is a verdict on the token you passed, not on the session.

Unity

static CallCredential Bearer(string accessToken)

Parameter	Type	Required	Description
`accessToken`	`string`	Required	The access token to use for this call.

Returns: CallCredential

If the token is null, empty, or whitespace, it becomes an invalid credential, and the call fails with InvalidArgument before it reaches the network. Because no exception is thrown here, you can pass a value read from storage as is without checking it, and the failure is delivered through the same result channel on every platform.