Table of Contents

Interface IApiKeyManager

Namespace
Excalibur.A3.Governance.NonHumanIdentity
Assembly
Excalibur.A3.Governance.Abstractions.dll

Manages API key lifecycle: creation, revocation, rotation, and validation.

public interface IApiKeyManager

Remarks

Keys are stored as SHA-256 hashes -- plaintext is never persisted. The plaintext key is returned exactly once at creation/rotation via ApiKeyCreationResult.

Mandatory expiry is enforced. Rotation is atomic: new key created + old key revoked in a single operation.

Methods

CreateKeyAsync(ApiKeyRequest, CancellationToken)

Creates a new API key for a principal.

Task<ApiKeyCreationResult> CreateKeyAsync(ApiKeyRequest request, CancellationToken cancellationToken)

Parameters

request ApiKeyRequest

The key creation request.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<ApiKeyCreationResult>

The creation result containing the plaintext key (returned once).

GetKeysByPrincipalAsync(string, CancellationToken)

Retrieves all active (non-revoked) keys for a principal.

Task<IReadOnlyList<ApiKeyMetadata>> GetKeysByPrincipalAsync(string principalId, CancellationToken cancellationToken)

Parameters

principalId string

The principal identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<ApiKeyMetadata>>

Metadata for all active keys belonging to the principal.

GetService(Type)

Gets a sub-interface or service from this manager.

object? GetService(Type serviceType)

Parameters

serviceType Type

The type of service to retrieve.

Returns

object

The service instance, or null if not supported.

RevokeKeyAsync(string, CancellationToken)

Revokes an existing API key.

Task RevokeKeyAsync(string keyId, CancellationToken cancellationToken)

Parameters

keyId string

The key identifier to revoke.

cancellationToken CancellationToken

Cancellation token.

Returns

Task

RotateKeyAsync(string, CancellationToken)

Atomically rotates an API key: revokes the existing key and creates a new one with the same principal, scopes, and description.

Task<ApiKeyCreationResult> RotateKeyAsync(string keyId, CancellationToken cancellationToken)

Parameters

keyId string

The identifier of the key to rotate.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<ApiKeyCreationResult>

The creation result containing the new plaintext key (returned once).

Exceptions

InvalidOperationException

The key does not exist or has already been revoked.

ValidateKeyAsync(string, CancellationToken)

Validates an API key and returns its metadata if valid.

Task<ApiKeyValidationResult> ValidateKeyAsync(string apiKey, CancellationToken cancellationToken)

Parameters

apiKey string

The plaintext API key to validate.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<ApiKeyValidationResult>

The validation result.