> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up a Microsoft Azure OAuth App

> Create your own Microsoft app registration so you can connect Outlook to Hiveku

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.

<Info>
  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.
</Info>

## 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](https://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

<Steps>
  <Step title="Open Microsoft Entra ID">
    Go to [portal.azure.com](https://portal.azure.com), sign in, and navigate to **Microsoft Entra ID** (formerly Azure Active Directory) > **App registrations** > **New registration**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.

    <Warning>
      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).
    </Warning>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

<Steps>
  <Step title="Create a new secret in Azure">
    **Certificates & secrets > New client secret**. Copy the new value.
  </Step>

  <Step title="Update it in Hiveku">
    **Settings > OAuth Apps > Microsoft app > Edit > paste new secret**. Save.
  </Step>

  <Step title="Delete the old secret">
    Back in Azure, delete the expiring secret to keep your app surface minimal.
  </Step>
</Steps>

<Tip>
  Set a calendar reminder two weeks before your client secret expires. Expired secrets break existing connections — rotate ahead of the deadline.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="AADSTS50011: reply URL mismatch">
    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.
  </Accordion>

  <Accordion title="AADSTS700016: application not found in tenant">
    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.
  </Accordion>

  <Accordion title="AADSTS65001: user or admin has not consented">
    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.
  </Accordion>

  <Accordion title="Client secret expired">
    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.
  </Accordion>

  <Accordion title="User sees the wrong tenant picker">
    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.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={1}>
  <Card title="Connect Outlook" icon="envelope" href="/how-tos/connect-outlook">
    Use your Azure app to connect an Outlook or Microsoft 365 mailbox
  </Card>
</CardGroup>