Interface ISystemApiKeyManagementService

Namespace

Tharga.Team

Assembly

Tharga.Team.dll

User-facing management of system API keys — keys not bound to any team. All methods require the SystemManage scope and no team need be selected.

public interface ISystemApiKeyManagementService

Remarks

Separate from IApiKeyManagementService so each interface is wholly one kind: every operation there names the team it acts on, every operation here acts on none. That homogeneity is what lets the registration declare the rule once — AddSystemService here, AddTeamService there — instead of leaving it to a per-method annotation somebody has to remember on the next method added.

Methods

CreateSystemKeyAsync(string, string[], DateTime?, bool)

Creates a system key. When personal is true the key belongs to the caller, who must be a signed-in user; a caller can only ever create a key owned by themselves.

[RequireScope("apikey:system-manage")]
Task<IApiKey> CreateSystemKeyAsync(string name, string[] scopes, DateTime? expiryDate = null, bool personal = false)

Parameters

name string

scopes string[]

expiryDate DateTime?

personal bool

Returns

Task<IApiKey>

Remarks

SystemKeys decides what is allowed: Shared refuses personal with an InvalidOperationException, and Personal makes every key personal whatever personal says.

DeleteSystemKeyAsync(string)

[RequireScope("apikey:system-manage")]
Task DeleteSystemKeyAsync(string key)

Parameters

key string

Returns

Task

GetSystemKeysAsync(PrivateKeyScope)

Returns the system keys for the caller. Shared keys are always included; personal keys are included per personalKeys, intersected with the caller's entitlement (Mine = the caller's own; All = own, plus everyone's for an Oversee holder). The default lists shared keys only, as before personal system keys existed.

[RequireScope("apikey:system-manage")]
IAsyncEnumerable<IApiKey> GetSystemKeysAsync(PrivateKeyScope personalKeys = PrivateKeyScope.None)

Parameters

personalKeys PrivateKeyScope

Returns

IAsyncEnumerable<IApiKey>

LockSystemKeyAsync(string)

[RequireScope("apikey:system-manage")]
Task LockSystemKeyAsync(string key)

Parameters

key string

Returns

Task

RefreshSystemKeyAsync(string)

[RequireScope("apikey:system-manage")]
Task<IApiKey> RefreshSystemKeyAsync(string key)

Parameters

key string

Returns

Task<IApiKey>

Remarks

A personal key can be refreshed only by its owner or an Oversee holder; the same goes for lock, disable and delete.

SetSystemKeyDisabledAsync(string, bool)

Disables the key, or enables it again. A disabled key is refused at authentication but keeps its name, scopes, roles, tags and history — the reversible alternative to DeleteKeyAsync(string, string).

[RequireScope("apikey:system-manage")]
Task SetSystemKeyDisabledAsync(string key, bool disabled)

Parameters

key string

disabled bool

Returns

Task

Remarks

Refreshing a disabled key does not enable it. A refresh mints a new secret; it is not a decision to trust the key again, and the usual reason to refresh is the same suspected leak that prompted the disable.