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

# Admin: OAuth Provider Setup

> How to register OAuth apps and configure providers in the Noxus Admin panel

Before users can connect OAuth integrations (Google, Microsoft, Slack, Notion, etc.), an
administrator must register an OAuth application with each provider and enter the credentials
in the Noxus Admin panel.

<Info>
  **Who does this?** This is a one-time setup per provider, done by a Noxus platform
  administrator. Once configured, all workspace users can connect their own accounts without
  any further admin involvement.
</Info>

***

## How it works

```mermaid theme={null}
sequenceDiagram
    participant A  as Admin
    participant NP as Noxus Admin Panel
    participant P  as Provider (Google / Microsoft / …)
    participant U  as End User

    Note over A,P: One-time setup
    A->>P: Create OAuth app, copy Client ID & Secret
    A->>NP: Enter credentials in Admin → Integrations → Providers

    Note over U,P: Per-user, self-service
    U->>NP: Click "Connect" in Workspace Control
    NP->>P: OAuth consent flow
    P->>U: Grant access
    NP->>NP: Store tokens encrypted
```

***

## Step-by-step: Admin panel

<Steps>
  <Step title="Open the Admin panel">
    Navigate to **Admin → Integrations** in the sidebar (gear icon).
  </Step>

  <Step title="Find the provider">
    Switch to the **OAuth Providers** tab. Each provider shows its configuration status
    (green = configured, amber = missing credentials).
  </Step>

  <Step title="Click Configure">
    Click **Configure** (or **Update**) on the provider card. A dialog opens showing
    the required fields (Client ID, Client Secret, and optionally a Tenant ID for Microsoft).
  </Step>

  <Step title="Enter credentials">
    Paste the credentials you obtained from the provider's developer console (see
    provider-specific guides below).
  </Step>

  <Step title="Save">
    Click **Save**. The provider status changes to green. Users can now connect their accounts.
  </Step>
</Steps>

***

## Provider-specific setup guides

<AccordionGroup>
  <Accordion title="Google (Drive, Gmail, Sheets, Calendar)" icon="google">
    ### 1 — Create a Google Cloud project

    1. Go to [console.cloud.google.com](https://console.cloud.google.com) and create a new project
       (or use an existing one).

    ### 2 — Enable APIs

    Enable the APIs you need:

    | Service         | API to enable       |
    | :-------------- | :------------------ |
    | Google Drive    | Google Drive API    |
    | Gmail           | Gmail API           |
    | Google Sheets   | Google Sheets API   |
    | Google Calendar | Google Calendar API |

    Navigate to **APIs & Services → Library** and search for each API.

    ### 3 — Configure the OAuth consent screen

    1. Go to **APIs & Services → OAuth consent screen**.
    2. Select **External** (or Internal if restricting to your Google Workspace org).
    3. Fill in App name, support email, and developer email.
    4. Add **Authorized domains**: your Noxus instance domain (e.g. `noxus.yourcompany.com`).
    5. Add the required **Scopes** (you can add scopes or leave them blank — Noxus requests scopes
       dynamically per integration).
    6. Save and continue.

    ### 4 — Create OAuth 2.0 credentials

    1. Go to **APIs & Services → Credentials → Create Credentials → OAuth client ID**.
    2. Application type: **Web application**.
    3. Name: anything (e.g. "Noxus Production").
    4. **Authorised redirect URIs** — add exactly:
       ```
       https://<your-noxus-domain>/api/backend/integrations/oauth/callback
       ```
    5. Click **Create**. Copy the **Client ID** and **Client Secret**.

    ### 5 — Enter in Noxus Admin

    In **Admin → Integrations → OAuth Providers → Google Workspace**, enter:

    * **Client ID** — the value from step 4
    * **Client Secret** — the value from step 4
  </Accordion>

  <Accordion title="Microsoft 365 (Outlook, Teams, OneDrive, SharePoint)" icon="microsoft">
    ### Option A — OAuth (User-Delegated)

    User connects their own Microsoft account — actions appear as coming from that user.

    #### 1 — Register an app in Azure Entra ID

    1. Go to [portal.azure.com](https://portal.azure.com) → **Azure Active Directory → App registrations → New registration**.
    2. Name: anything (e.g. "Noxus OAuth").
    3. Supported account types: **Accounts in any organizational directory and personal Microsoft accounts**
       (or restrict to your tenant if needed).
    4. Redirect URI: `Web` → `https://<your-noxus-domain>/api/backend/integrations/oauth/callback`
    5. Click **Register**.

    #### 2 — Add API permissions

    Go to **API permissions → Add a permission → Microsoft Graph → Delegated permissions**:

    | Service      | Permissions                                |
    | :----------- | :----------------------------------------- |
    | Outlook mail | `Mail.Read`, `Mail.Send`, `Mail.ReadWrite` |
    | Calendar     | `Calendars.Read`, `Calendars.ReadWrite`    |
    | OneDrive     | `Files.Read.All`, `Files.ReadWrite.All`    |
    | SharePoint   | `Sites.Read.All`, `Sites.ReadWrite.All`    |
    | Teams        | `ChannelMessage.Read.All`, `Chat.Read`     |

    Click **Grant admin consent for \[your tenant]**.

    #### 3 — Create a client secret

    Go to **Certificates & secrets → New client secret**. Copy the **Value** (not the ID).

    #### 4 — Enter in Noxus Admin

    In **Admin → Integrations → OAuth Providers → Microsoft 365 (OAuth)**, enter:

    * **Client ID** — Application (client) ID from the Overview page
    * **Client Secret** — the secret value from step 3
    * **Tenant ID** *(optional)* — leave blank for multi-tenant, or enter your Directory (tenant) ID to restrict to your org

    ***

    ### Option B — Service Principal (Application Permissions)

    Application acts with its own identity — no user sign-in required. Suitable for
    background workflows that need broad org-wide access.

    <Info>
      Service Principal requires **admin consent** from a Microsoft Global Admin and grants
      broader access than OAuth. Use OAuth unless you specifically need app-level permissions.
    </Info>

    #### 1 — Register a separate app in Azure Entra ID

    Follow steps 1–3 above, but select **Application permissions** instead of Delegated.

    Required permissions for Service Principal:

    | Service | Permissions                                |
    | :------ | :----------------------------------------- |
    | Mail    | `Mail.Read`, `Mail.Send`, `Mail.ReadWrite` |
    | Files   | `Files.Read.All`, `Files.ReadWrite.All`    |
    | Sites   | `Sites.Read.All`, `Sites.ReadWrite.All`    |
    | Teams   | `ChannelMessage.Read.All`                  |

    #### 2 — Enter in Noxus Admin

    In **Admin → Integrations → OAuth Providers → Microsoft 365 (Service Principal)**, enter:

    * **Tenant ID** — your Directory (tenant) ID
    * **Client ID** — Application (client) ID
    * **Client Secret** — the secret value
  </Accordion>

  <Accordion title="Slack" icon="slack">
    ### 1 — Create a Slack app

    1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App → From scratch**.
    2. Name your app (e.g. "Noxus") and pick your workspace for development.

    ### 2 — Configure OAuth

    1. In the left sidebar, go to **OAuth & Permissions**.
    2. Under **Redirect URLs**, add:
       ```
       https://<your-noxus-domain>/api/backend/integrations/oauth/callback
       ```
    3. Under **Bot Token Scopes**, add:
       * `channels:read`, `channels:history`
       * `chat:write`
       * `users:read`
       * `files:read`, `files:write`

    ### 3 — Get credentials

    Go to **Basic Information** → **App Credentials**. Copy:

    * **Client ID**
    * **Client Secret**

    ### 4 — Enter in Noxus Admin

    In **Admin → Integrations → OAuth Providers → Slack**, enter the Client ID and Client Secret.
  </Accordion>

  <Accordion title="Notion" icon="book">
    ### 1 — Create a Notion integration

    1. Go to [www.notion.com/my-integrations](https://www.notion.com/my-integrations) → **New integration**.
    2. Name: anything (e.g. "Noxus").
    3. Select the workspace.
    4. Under **Capabilities**, choose **Read content**, **Update content**, **Insert content**.
    5. Under **Distribution**, switch to **Public** (required for OAuth).

    ### 2 — Configure OAuth

    In the integration settings, under **OAuth Domain & URIs**:

    * **Redirect URIs**: `https://<your-noxus-domain>/api/backend/integrations/oauth/callback`

    ### 3 — Get credentials

    Under **OAuth Credentials**, copy:

    * **OAuth client ID**
    * **OAuth client secret**

    ### 4 — Enter in Noxus Admin

    In **Admin → Integrations → OAuth Providers → Notion**, enter the OAuth client ID and client secret.
  </Accordion>

  <Accordion title="GitHub" icon="github">
    ### 1 — Create a GitHub OAuth App

    1. Go to **GitHub → Settings → Developer settings → OAuth Apps → New OAuth App**.
    2. Application name: anything (e.g. "Noxus").
    3. Homepage URL: your Noxus instance URL.
    4. Authorization callback URL:
       ```
       https://<your-noxus-domain>/api/backend/integrations/oauth/callback
       ```
    5. Click **Register application**.

    ### 2 — Get credentials

    On the app page, note the **Client ID**. Click **Generate a new client secret** and copy it.

    ### 3 — Enter in Noxus Admin

    In **Admin → Integrations → OAuth Providers → GitHub**, enter the Client ID and Client Secret.
  </Accordion>

  <Accordion title="HubSpot" icon="hubspot">
    ### 1 — Create a HubSpot app

    1. Go to [developers.hubspot.com](https://developers.hubspot.com) → **Manage apps → Create app**.
    2. Under **Auth**, find your **Client ID** and **Client Secret**.
    3. Add a redirect URL:
       ```
       https://<your-noxus-domain>/api/backend/integrations/oauth/callback
       ```
    4. Under **Scopes**, add the CRM scopes you need (contacts, companies, deals).

    ### 2 — Enter in Noxus Admin

    In **Admin → Integrations → OAuth Providers → HubSpot**, enter the Client ID and Client Secret.
  </Accordion>

  <Accordion title="Airtable" icon="table">
    ### 1 — Create an Airtable OAuth app

    1. Go to [airtable.com/create/oauth](https://airtable.com/create/oauth) → **Register new OAuth integration**.
    2. Redirect URI:
       ```
       https://<your-noxus-domain>/api/backend/integrations/oauth/callback
       ```
    3. Select required scopes: `data.records:read`, `data.records:write`, `data.schemas:read`.

    ### 2 — Get credentials

    Copy the **Client ID** and **Client Secret** from the app page.

    ### 3 — Enter in Noxus Admin

    In **Admin → Integrations → OAuth Providers → Airtable**, enter the Client ID and Client Secret.
  </Accordion>
</AccordionGroup>

***

## Redirect URI reference

All providers require the same callback URL:

```
https://<your-noxus-domain>/api/backend/integrations/oauth/callback
```

Replace `<your-noxus-domain>` with the actual hostname of your Noxus instance
(e.g. `app.noxus.ai` or `noxus.yourcompany.com`).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="redirect_uri_mismatch error" icon="circle-x">
    The redirect URI registered with the provider does not exactly match the one Noxus sends.
    Ensure there are **no trailing slashes**, the protocol is `https://`, and the path is
    `/api/backend/integrations/oauth/callback`.
  </Accordion>

  <Accordion title="invalid_client error" icon="circle-x">
    The Client ID or Client Secret is incorrect. Re-copy the values from the provider's
    developer console — make sure there are no leading/trailing spaces.
  </Accordion>

  <Accordion title="Provider shows as 'not configured' after saving" icon="circle-x">
    Ensure the **Client ID** field is not empty. If the provider requires a Tenant ID
    (Microsoft), make sure it is also filled in.
  </Accordion>

  <Accordion title="Users see 'Authorization in progress - you may see a warning screen'" icon="alert-triangle">
    This means the OAuth app's consent screen is in **testing/unverified** mode with the provider.
    For Google, publish the app in the OAuth consent screen settings. For others, complete
    the provider's app verification process.
  </Accordion>
</AccordionGroup>