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
requestApiKeyRequestThe key creation request.
cancellationTokenCancellationTokenCancellation 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
principalIdstringThe principal identifier.
cancellationTokenCancellationTokenCancellation 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
serviceTypeTypeThe type of service to retrieve.
Returns
RevokeKeyAsync(string, CancellationToken)
Revokes an existing API key.
Task RevokeKeyAsync(string keyId, CancellationToken cancellationToken)
Parameters
keyIdstringThe key identifier to revoke.
cancellationTokenCancellationTokenCancellation token.
Returns
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
keyIdstringThe identifier of the key to rotate.
cancellationTokenCancellationTokenCancellation 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
apiKeystringThe plaintext API key to validate.
cancellationTokenCancellationTokenCancellation token.
Returns
- Task<ApiKeyValidationResult>
The validation result.