Using OAuth for Authentication

OAuth (Open Authorization) is an industry-standard protocol that enables secure, delegated access to resources without requiring users to share credentials such as usernames and passwords.

Instead of storing static credentials on a device or application, OAuth allows a trusted third-party service (such as Google, Microsoft, or Slack) to issue time-limited access tokens. These tokens allow an Algo device to interact with the service on behalf of a user or system, without exposing sensitive login information.

Note

Your device firmware must be on v5.7 or later to use this feature.

Why is OAuth Needed?

Many modern APIs no longer support permanent API keys or basic authentication due to security risks. Instead, they rely on OAuth to provide secure, time-bound access.

OAuth enables continuous access through token refresh mechanisms. When an access token expires, it can be automatically renewed using a refresh token, without requiring manual intervention. As a result, when an API call is triggered, the device is already authenticated and authorized, ensuring the request is accepted by the third-party service. This is especially important for providers such as Microsoft and Google, where tokens frequently expire.

OAuth also improves security by eliminating the need to store or transmit credentials directly. Access is scoped, limited, and can be revoked at any time.

OAuth Use Cases

OAuth is commonly used when an Algo device needs to securely interact with external services.

For example, you can use OAuth Profiles to send API calls that:

• Send messages to Microsoft Teams or Slack

• Create meetings in Zoom or Webex

• Write files to Google Drive or SharePoint

• Send emails using Outlook or Gmail APIs

This is the general procedure when using OAuth in API calls.

OAuth Profiles

An OAuth profile is a configuration on the Algo device that stores all required OAuth parameters for a specific integration.

Once created, an OAuth profile can be reused across multiple API actions, simplifying configuration and management.

You can create an OAuth profile from scratch using the GENERIC provider type, or use predefined templates for supported services.

Note

• Your device firmware must be 5.7 or later.

• The configuration procedure and required information for creating an OAuth profile vary by service provider.

  Refer to your service provider’s user guide for detailed instructions and requirements.

To create an OAuth Profile:

1. Log in to your device’s web interface using HTTPS.

   HTTPS is required by the OAuth authorization process.

2. Go to the Advanced Settings → OAuth.

3. Set a Name for your OAuth profile.

4. Select a Provider Type.

   • GENERIC: Create a custom OAuth profile.

   • MICROSOFT_TEAMS: Microsoft Teams template.

   • MICROSOFT_OUTLOOK: Microsoft Outlook template.

   • GOOGLE_DOCS: Google Docs template.

   • RINGCENTRAL: RingCentral template.

   • WEBEX: Cisco Webex template.

   • ZOOM: Zoom template.

   • SLACK: Slack template.

5. Configure the OAuth profile.

6. Test the OAuth profile to make sure it works.

Related Links:

• Examples: OAuth Profile Creation, Testing, and Usage in API CallsI won

Examples: OAuth Profile Creation, Testing, and Usage

These examples demonstrate how to:

• Integrate an Algo device with a service provider using OAuth

• Verify the configuration

• Send API calls using the OAuth profile

  The examples show how to configure an Algo 8450 button to trigger API calls, but the same approach can be applied to other devices.

The following configuration examples are available:

• Example: OAuth Configuration for Microsoft Teams

• Example: OAuth Configuration for Slack

• Example: OAuth Configuration for Cisco Webex

• Example: OAuth Configuration for Zoom

• Example: OAuth Configuration for Microsoft Outlook

• Example: OAuth Configuration for Google Docs

• Example: OAuth Configuration for Google Calendar

• Example: OAuth Configuration for RingCentral

Securing Your OAuth Profiles Using a Security Key

By default, OAuth secrets are stored in plain text in your device’s configuration file.

To improve security, it is strongly recommended to configure a Security Key. This encrypts sensitive information such as:

• Client Secret

• Extra Parameters

• Refresh Token

• Authorization Code

Note

If OAuth configurations are exported and imported into another device, the same Security Key must be entered to decrypt the stored information. Otherwise, the imported OAuth profiles will not function.

If the Security Key is unavailable, you must re-enter the Client Secret and perform Start Authorization for your OAuth profiles again.

This ensures that only authorized users can access and use the OAuth profile configurations.

Setting a Security Key for Your OAuth Profiles

Once a Security Key is configured, it applies to all OAuth profiles (both existing and new) and encrypts sensitive authentication data in the configuration file.

Note

• The Security Key cannot be retrieved after being saved.

• Store it securely for future use (e.g., restoring backups).

• Without the key, restored OAuth profiles will not function. You will need to enter the Client Secret key and re-perform the Start Authorization.

To set a Security Key:

1. Log in to your device’s web interface using HTTPS.

   HTTPS is required by the OAuth authorization process.

2. Go to the Advanced Settings → OAuth.

3. Go to the OAuth Secret Key section and enter your key.

4. Select Save Key.

   The sensitive information in all your OAuth profiles (including the profiles created before and after the security key creation) is encrypted in the configuration file.

   If you select  Download Configuration File from Systems → Maintenance → Backup / Restore Configuration, you can find encrypted values with a prefix enc:v1:.

Updating Security Key for Your OAuth Profiles

You can update the security key for your OAuth profiles.

Note

Updating the Security Key will render all existing OAuth profiles non-functional.

You must re-enter the Client Secret and perform Start Authorization again for each existing OAuth profile.

This ensures that only authorized users can access and use the OAuth configuration.

To update a Security Key:

1. Log in to your device’s web interface using HTTPS.

   HTTPS is required by the OAuth authorization process.

2. Go to the Advanced Settings → OAuth.

3. Go to the OAuth Secret Key section and enter your new key.

4. Select Save Key.

5. When prompted to confirm the action, select OK.

6. Edit each of your existing OAuth profiles and re-enter the Client Secret.

7. Select Start Authorization.

8. Select Update Profile.

Exporting OAuth Profiles to Another Device

OAuth profile data is stored in the device configuration file. You can export it from one device and import it into another.

Note

If a Security Key is configured on the source device, you must enter the same key on the target device. Otherwise, the OAuth profiles will not function.

To export OAuth profile settings and import into Another Devcie:

1. Log in to the web interface of the source device.

2. Go to Systems → Maintenance → Backup / Restore Configuration.

3. Select Download Configuration File.

4. Open the file and locate entries starting with oauth.profile

5. Copy those entries into a new .txt file.

6. Log in to the web interface of your target device.

7. If a Security Key is set on the source device, enter the same key in the target device:

   1. Go to Advanced Settings → OAuth.

   2. Go to the OAuth Secret Key section and enter the same Security Key you set in the source device.

   3. Select Save Key.

8. Go to Systems → Maintenance → Backup / Restore Configuration.

9. Click Choose File and select your new configuration file.

10. Select Restore.

11. Select Reboot.

    You can find the OAuth Profiles in Advanced Settings → OAuth.

    Note

    • Do not modify the imported profile

    • Do not re-perform Start Authorization

    This is because some authentication information (e.g., the PKCE Redirect URI) is tied to the source device. Re-authorizing from a different device will fail.