Skip to main content
To connect Outlook or Microsoft 365 mailboxes, you register a Microsoft Entra (Azure AD) app once in your tenant and reuse it across every Outlook connection in Hiveku.
This is the BYOK (Bring Your Own Key) model. Your users see your organization on the Microsoft consent screen, and API usage flows through your Microsoft tenant — not through a shared Hiveku app.

​
Why BYOK?

  • Your branding on the consent screen
  • Your scopes — request only what you need
  • Your tenant controls — admin consent, conditional access, and audit logs run through your Azure tenant
  • Your secret lifecycle — rotate or revoke at will

​
Before You Start

You’ll need:
  • A Microsoft account with access to portal.azure.com
  • Permissions to register apps in your Microsoft Entra ID tenant (or a personal Microsoft account for multi-tenant apps)
  • Access to Hiveku as an admin to register the app under Settings > OAuth Apps

​
Register the Azure App

1

Open Microsoft Entra ID

Go to portal.azure.com, sign in, and navigate to Microsoft Entra ID (formerly Azure Active Directory) > App registrations > New registration.
2

Register the app

  • Name: something recognizable, e.g., Acme Hiveku
  • Supported account types: pick based on who will authorize:
    • Single tenant — only users in your Microsoft 365 tenant
    • Multitenant — users in any Microsoft 365 tenant
    • Multitenant + personal — any work, school, or personal Microsoft account (most flexible, recommended unless you have a reason to restrict)
  • Redirect URI:
    • Platform: Web
    • URI: exactly https://app.hiveku.com/api/oauth/microsoft/callback
Click Register.
3

Add Microsoft Graph API permissions

From your app page, go to Manage > API permissions > Add a permission > Microsoft Graph > Delegated permissions.Add these permissions for Outlook Mail:
  • offline_access — required to get a refresh token so the connection doesn’t expire
  • Mail.ReadWrite — read, organize, and manage mail
  • Mail.Send — send mail
If you also plan to use calendar features (e.g., for a sales booking agent):
  • Calendars.ReadWrite
For read-only or send-only use cases, you can add Mail.Read or just Mail.Send instead of the full set.If you’re a tenant admin, click Grant admin consent for [tenant] — this pre-consents the permissions for all users in your tenant. Otherwise, each user will consent individually on first connection (or an admin will need to consent later if admin consent is required for any scope).
4

Create a client secret

Go to Manage > Certificates & secrets > Client secrets > New client secret.
  • Description: e.g., Hiveku prod
  • Expires: choose an expiry — 24 months is a reasonable balance between security and rotation frequency
Click Add. Microsoft shows the secret Value once — copy it immediately.
The client secret Value is only shown at the moment of creation. If you navigate away without copying it, you have to create a new secret. Don’t confuse it with the Secret ID (a reference identifier, not the secret itself).
5

Note your Tenant ID

From the app Overview page, copy:
  • Application (client) ID
  • Directory (tenant) ID
The Tenant ID determines which accounts can authorize:
  • Paste your actual tenant ID for single-tenant (users must be in this tenant)
  • Use common to allow any work, school, or personal Microsoft account to authorize
  • Use organizations to allow any work or school account but not personal
  • Use consumers for personal Microsoft accounts only
For most BYOK setups where you want flexibility, common is the right choice.
6

Register the app in Hiveku

In Hiveku, go to Settings > OAuth Apps > Add.
  • Provider: Microsoft
  • Name: a label just for you, e.g., Acme Microsoft
  • Client ID: the Application (client) ID from Azure
  • Client Secret: the Value you copied from Azure
  • Tenant: common or your specific tenant ID
Save.

​
Verify It Works

Start an Outlook connection from CRM > Email Connections > Add > Outlook. Select your registered Microsoft OAuth app. You should be redirected to a Microsoft consent screen showing your app name and the scopes you requested. After consent, you should land back in Hiveku with the Outlook connection saved and showing your email address.

​
Rotating the Client Secret

Secrets expire. Before expiry:
1

Create a new secret in Azure

Certificates & secrets > New client secret. Copy the new value.
2

Update it in Hiveku

Settings > OAuth Apps > Microsoft app > Edit > paste new secret. Save.
3

Delete the old secret

Back in Azure, delete the expiring secret to keep your app surface minimal.
Set a calendar reminder two weeks before your client secret expires. Expired secrets break existing connections — rotate ahead of the deadline.

​
Troubleshooting

The redirect URI in Azure doesn’t match what Hiveku sent. Open App registrations > [your app] > Authentication and confirm the Web platform redirect URI is exactly:
https://app.hiveku.com/api/oauth/microsoft/callback
Watch for a missing https://, /callback, or a typo.
The tenant in the Hiveku config doesn’t include the user’s account. If you’re using a single-tenant configuration, users outside that tenant can’t authorize. Either switch Hiveku’s Tenant field to common or make sure users are in the tenant you specified.
Some Graph scopes require admin consent. Your Microsoft 365 admin should go to Azure Portal > App registrations > [your app] > API permissions > Grant admin consent for [tenant]. After that, regular users can consent on their own.
Existing connections start failing to refresh tokens. Create a new secret in Azure and update it in Hiveku > Settings > OAuth Apps. Affected users may need to reconnect their Outlook connection once.
If users with personal Microsoft accounts see errors, your app may be set to Accounts in this organizational directory only. Change Supported account types in Azure to include personal accounts, or use common as the tenant.

​
What’s Next?

Connect Outlook

Use your Azure app to connect an Outlook or Microsoft 365 mailbox