Class OverkizClient
- Namespace
- OverKizApi
- Assembly
- OverKizApi.dll
C# client for the Overkiz API, providing similar capabilities to the Python python-overkiz-api library. Supports cloud (standard, Somfy OAuth, CozyTouch JWT, Nexity SSO) and local API modes.
public sealed class OverkizClient : IAsyncDisposable
- Inheritance
-
OverkizClient
- Implements
- Inherited Members
Remarks
Independent reads may overlap. Authentication, gateway and listener changes are coordinated with reads. Disposal cancels pending work and prevents late publication. Callers must coordinate their own mutations of returned models and dedicate any supplied HttpClient to this client.
Constructors
OverkizClient(string, string, OverkizServer, string?, HttpClient?)
Creates a new OverkizClient.
public OverkizClient(string username, string password, OverkizServer server, string? token = null, HttpClient? httpClient = null)
Parameters
usernamestringAccount username / email.
passwordstringAccount password.
serverOverkizServerTarget OverkizServer (use SupportedServers).
tokenstringPre-existing bearer token (optional; bypasses login).
httpClientHttpClientOptional externally-managed HttpClient. If null, one is created internally.
Properties
ApiType
Whether the client is operating against the cloud API or a local gateway API.
public APIType ApiType { get; }
Property Value
- APIType
Whether the client is operating against the cloud API or a local gateway API.
Devices
All devices from the most recently retrieved setup. Populated by GetSetup(bool); empty until that method is called.
public List<Device> Devices { get; }
Property Value
- List<Device>
All devices from the most recently retrieved setup. Populated by GetSetup(bool); empty until that method is called.
EventListenerId
The event listener ID returned by the last successful RegisterEventListener() call, or null if no listener is currently registered.
public string? EventListenerId { get; }
Property Value
- string
The event listener ID returned by the last successful RegisterEventListener() call, or null if no listener is currently registered.
Gateways
All gateways from the most recently retrieved setup. Populated by GetSetup(bool); empty until that method is called.
public List<Gateway> Gateways { get; }
Property Value
- List<Gateway>
All gateways from the most recently retrieved setup. Populated by GetSetup(bool); empty until that method is called.
Password
Account password used to authenticate with the Overkiz server.
public string Password { get; }
Property Value
- string
Account password used to authenticate with the Overkiz server.
SelectedGatewayId
The currently selected Rexel gateway ID, or null if none has been selected.
public string? SelectedGatewayId { get; }
Property Value
Server
The target server this client is connected to.
public OverkizServer Server { get; }
Property Value
- OverkizServer
The target server this client is connected to.
Setup
The most recently retrieved Setup, or null if GetSetup(bool) has not yet been called.
public Setup? Setup { get; }
Property Value
- Setup
The most recently retrieved Setup, or null if GetSetup(bool) has not yet been called.
Username
Account username or e-mail address used to authenticate with the Overkiz server.
public string Username { get; }
Property Value
- string
Account username or e-mail address used to authenticate with the Overkiz server.
Methods
ActivateDeveloperMode(string)
Activates developer mode for a gateway. This is required on supported gateways before local developer-mode tokens can be used.
public Task ActivateDeveloperMode(string gatewayId)
Parameters
gatewayIdstringSerial number of the gateway. For Rexel cloud endpoints, use ExternalId.
Returns
- Task
A task that completes when the activation request finishes.
ActivateLocalToken(string, string, string, string)
Registers a generated local API token on the gateway so that it can be used for local API calls.
public Task<string> ActivateLocalToken(string gatewayId, string token, string label, string scope = "devmode")
Parameters
gatewayIdstringSerial number of the gateway to register the token on. For Rexel cloud endpoints, use ExternalId.
tokenstringThe raw token string returned by GenerateLocalToken(string).
labelstringA human-readable label to identify this token in the token list.
scopestringAccess scope to grant (default
"devmode").
Returns
Exceptions
- OverkizException
Thrown when the server does not return a request ID.
CancelExecution(string)
Cancels a running or queued execution.
public Task CancelExecution(string execId)
Parameters
execIdstringThe execution ID returned by ExecuteDeviceAction(string, IEnumerable<Command>, string) or ExecuteScenario(string).
Returns
- Task
A task that completes when the cancellation request finishes.
CozytouchLogin()
Authenticates against the Atlantic/CozyTouch OAuth endpoint and returns
the JWT token required for the subsequent Overkiz login call.
public Task<string> CozytouchLogin()
Returns
Exceptions
- CozyTouchBadCredentialsException
Thrown when the Atlantic OAuth server rejects the credentials.
- CozyTouchServiceException
Thrown when the Atlantic token or JWT endpoint returns an unexpected response.
DeactivateDeveloperMode(string)
Deactivates developer mode for a gateway. Some gateways reject this endpoint even when they support reading developer-mode state.
public Task DeactivateDeveloperMode(string gatewayId)
Parameters
gatewayIdstringSerial number of the gateway. For Rexel cloud endpoints, use ExternalId.
Returns
- Task
A task that completes when the deactivation request finishes.
DeleteLocalToken(string, string)
Revokes and deletes a local API token.
public Task<bool> DeleteLocalToken(string gatewayId, string uuid)
Parameters
gatewayIdstringSerial number of the gateway the token belongs to. For Rexel cloud endpoints, use ExternalId.
uuidstringUUID of the token to delete (see Uuid).
Returns
DiscoverRexelGateways()
Discovers Rexel homes and gateways available to the current bearer token.
public Task<IReadOnlyList<GatewayCandidate>> DiscoverRexelGateways()
Returns
- Task<IReadOnlyList<GatewayCandidate>>
A read-only list of gateway candidates.
Exceptions
- UnsupportedOperationException
Thrown when the current server is not Rexel.
- InvalidOperationException
Thrown when no bearer token is available.
DisposeAsync()
Releases resources owned by this client. If an event listener is registered it is unregistered (best-effort) before disposal. If the HttpClient was created internally it is also disposed.
public ValueTask DisposeAsync()
Returns
- ValueTask
A task that completes when listener cleanup and resource disposal finish.
ExecuteDeviceAction(string, IEnumerable<Command>, string)
Sends a set of commands to a device as a single execution action.
public Task<string> ExecuteDeviceAction(string deviceUrl, IEnumerable<Command> commands, string label = "Execute")
Parameters
deviceUrlstringURL of the target device.
commandsIEnumerable<Command>One or more Command objects to execute.
labelstringOptional human-readable label recorded in the execution history.
Returns
Exceptions
- OverkizException
Thrown when the server does not return an execution ID.
ExecuteScenario(string)
Triggers immediate execution of a stored scenario.
public Task<string> ExecuteScenario(string oid)
Parameters
Returns
Exceptions
- OverkizException
Thrown when the server does not return an execution ID.
ExecuteScheduledScenario(string, long)
Schedules a scenario to execute at a specific point in time.
public Task<string> ExecuteScheduledScenario(string oid, long timestamp)
Parameters
oidstringThe OID of the scenario to schedule.
timestamplongUnix epoch millisecond timestamp at which to trigger the scenario.
Returns
Exceptions
- OverkizException
Thrown when the server does not return a trigger ID.
FetchEvents()
Fetches all queued events from the registered event listener and clears the server-side queue. Call this method repeatedly (polling) to receive device state change notifications.
public Task<IReadOnlyList<EventObject>> FetchEvents()
Returns
- Task<IReadOnlyList<EventObject>>
A list of EventObject objects; may be empty if no events are pending.
Exceptions
- NoRegisteredEventListenerException
Thrown when no event listener is registered. Call RegisterEventListener() first.
FetchEvents(bool)
Fetches queued events, optionally registering or recovering the listener automatically.
public Task<IReadOnlyList<EventObject>> FetchEvents(bool autoRegister)
Parameters
autoRegisterboolWhen true, registers a missing listener and allows one recovery after an explicit listener or session rejection.
Returns
- Task<IReadOnlyList<EventObject>>
The queued events; may be empty.
Remarks
Authentication refresh completes before the listener URL is constructed. Recovery is bounded to one replacement per fetch. Timeouts and other transport failures are not retried because fetching consumes events. Reauthentication requires cloud credentials; rejected local or externally managed tokens are not retried.
Exceptions
- NoRegisteredEventListenerException
No listener is registered and automatic registration is disabled, or the server rejects recovery.
GenerateLocalToken(string)
Generates a new local API token for the specified gateway. The token must then be activated with ActivateLocalToken(string, string, string, string) before it can be used.
public Task<string> GenerateLocalToken(string gatewayId)
Parameters
gatewayIdstringSerial number of the gateway to generate a token for. For Rexel cloud endpoints, use ExternalId rather than the header-scoping GatewayId.
Returns
- Task<string>
The raw token string to pass to ActivateLocalToken(string, string, string, string).
Exceptions
- OverkizException
Thrown when the server does not return a token.
GetCurrentExecutions()
Returns all executions that are currently active (in-progress or queued) on the gateway.
public Task<IReadOnlyList<Execution>> GetCurrentExecutions()
Returns
- Task<IReadOnlyList<Execution>>
A read-only list of Execution objects; empty if nothing is running.
GetDeveloperMode(string)
Returns the current developer-mode status for a gateway.
public Task<DeveloperMode> GetDeveloperMode(string gatewayId)
Parameters
gatewayIdstringSerial number of the gateway. For Rexel cloud endpoints, use ExternalId.
Returns
- Task<DeveloperMode>
A DeveloperMode object describing whether developer mode is active.
GetDevice(string)
Returns a single device identified by its URL.
public Task<Device> GetDevice(string deviceUrl)
Parameters
deviceUrlstringThe device URL (e.g.
io://1234-5678-9012/12345678).
Returns
Exceptions
- OverkizException
Thrown when the response cannot be deserialised.
GetDeviceStates(string)
Returns the current live states for a device.
public Task<IReadOnlyList<State>> GetDeviceStates(string deviceUrl)
Parameters
deviceUrlstringThe device URL to query.
Returns
- Task<IReadOnlyList<State>>
A read-only list of State objects.
GetDevices()
Returns all devices registered across all gateways in the setup.
public Task<IReadOnlyList<Device>> GetDevices()
Returns
- Task<IReadOnlyList<Device>>
A read-only list of Device objects.
GetExecutionHistory()
Returns the execution history log stored on the gateway.
public Task<IReadOnlyList<HistoryExecution>> GetExecutionHistory()
Returns
- Task<IReadOnlyList<HistoryExecution>>
A read-only list of HistoryExecution records, most-recent first.
GetGateways()
Returns all gateways registered in the setup.
public Task<IReadOnlyList<Gateway>> GetGateways()
Returns
- Task<IReadOnlyList<Gateway>>
A read-only list of Gateway objects.
GetLocalTokens(string, string)
Returns all active local API tokens for a gateway filtered by scope.
public Task<IReadOnlyList<LocalToken>> GetLocalTokens(string gatewayId, string scope = "devmode")
Parameters
gatewayIdstringSerial number of the gateway to query. For Rexel cloud endpoints, use ExternalId.
scopestringToken scope to filter by (default
"devmode").
Returns
- Task<IReadOnlyList<LocalToken>>
A read-only list of LocalToken descriptors.
GetPlaces()
Returns the root of the place hierarchy (house → floors → rooms).
public Task<Place> GetPlaces()
Returns
Exceptions
- OverkizException
Thrown when the response cannot be deserialised.
GetScenarios()
Returns all named scenarios (action groups) stored in the setup.
public Task<IReadOnlyList<Scenario>> GetScenarios()
Returns
- Task<IReadOnlyList<Scenario>>
A read-only list of Scenario objects.
GetSetup(bool)
Retrieves the complete home setup including all gateways, devices, zones, places and location.
The result is cached; pass refresh as true to force a fresh API call.
public Task<Setup> GetSetup(bool refresh = false)
Parameters
Returns
Exceptions
- OverkizException
Thrown when the response cannot be deserialised.
GetSetupOption(string)
Returns a specific option subscription by option ID.
public Task<OptionObject?> GetSetupOption(string option)
Parameters
optionstringOption ID to look up (e.g.
"ADVANCED_SCENARIOS").
Returns
- Task<OptionObject>
The OptionObject, or null if the option is not subscribed.
GetSetupOptionParameter(string, string)
Returns a single configuration parameter of a setup option.
public Task<OptionParameter?> GetSetupOptionParameter(string option, string parameter)
Parameters
Returns
- Task<OptionParameter>
The OptionParameter, or null if not found.
GetSetupOptions()
Returns all option subscriptions active on the authenticated setup.
public Task<IReadOnlyList<OptionObject>> GetSetupOptions()
Returns
- Task<IReadOnlyList<OptionObject>>
A read-only list of OptionObject objects.
Login(bool)
Authenticate and open an API session. Must be called before other operations unless a token was supplied.
public Task<bool> Login(bool registerEventListener = true)
Parameters
registerEventListenerboolRegister an event listener after login (default true).
Returns
NexityLogin()
Authenticates against the Nexity AWS Cognito SRP endpoint and returns the SSO token
required for the subsequent Overkiz login call.
public Task<string> NexityLogin()
Returns
Remarks
This method is a stub. Nexity authentication requires the AWS Cognito SRP protocol
which depends on AWSSDK.CognitoIdentityProvider. Add that package and override
(or replace) this method with a real SRP implementation.
Exceptions
- NotSupportedException
Always thrown by the default stub implementation.
OpenLocalPairing(string)
Opens the local pairing window on a gateway for approximately 180 seconds. During this period, additional local tokens may be registered directly on the gateway.
public Task OpenLocalPairing(string gatewayId)
Parameters
gatewayIdstringSerial number of the gateway. For Rexel cloud endpoints, use ExternalId.
Returns
- Task
A task that completes when the pairing request succeeds.
RefreshAllDeviceStates()
Asks the gateway to refresh all device states from the physical devices. Updated states will be pushed through the event listener.
public Task RefreshAllDeviceStates()
Returns
- Task
A task that completes when the refresh request has been accepted; device state updates arrive separately.
RefreshToken()
Refreshes the Somfy access token using the stored refresh token. This is called automatically by OverKizApi.OverkizClient.RefreshTokenIfExpired() when the token is near expiry; you do not normally need to call it manually.
public Task RefreshToken()
Returns
- Task
A task that completes when token refresh finishes, or immediately if refresh is not applicable.
Remarks
No-op if the current server is not SupportedServers[SomfyEurope].
Exceptions
- InvalidOperationException
Thrown when no refresh token is available (i.e. Login(bool) was not called first).
- SomfyBadCredentialsException
Thrown when the refresh token has been revoked.
- SomfyServiceException
Thrown when the Somfy token endpoint returns an unexpected response.
RegisterEventListener()
Register an event listener to receive device state changes.
public Task RegisterEventListener()
Returns
- Task
A task that completes when the listener has been registered.
Remarks
The assigned listener ID is stored in EventListenerId after this call completes.
Exceptions
- OverkizException
Thrown when the server does not return a valid listener ID.
SelectRexelGateway(string)
Selects the Rexel gateway to scope subsequent requests to.
public void SelectRexelGateway(string gatewayId)
Parameters
gatewayIdstringGateway identifier returned by DiscoverRexelGateways().
Exceptions
- UnsupportedOperationException
Thrown when the current server is not Rexel.
SomfyTahomaGetAccessToken()
Authenticate via Somfy identity and acquire an access token.
public Task<string> SomfyTahomaGetAccessToken()
Returns
Exceptions
- SomfyBadCredentialsException
Thrown when the supplied credentials are rejected by the Somfy OAuth server.
- SomfyServiceException
Thrown when the Somfy token endpoint returns an unexpected response.
UnregisterEventListener()
Unregisters the event listener and clears EventListenerId. Safe to call when no listener is registered (no-op).
public Task UnregisterEventListener()
Returns
- Task
A task that completes when listener cleanup finishes.