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

# Authentication

> Understanding authentication methods for integrations

Noxus supports multiple authentication methods to securely connect to external services.

## Common Authentication Methods

<Tabs>
  <Tab title="OAuth 2.0">
    **User-delegated access with secure token exchange**

    ### How It Works

    ```mermaid theme={null}
    sequenceDiagram
        participant U as User
        participant N as Noxus
        participant S as Service Provider
        
        U->>N: Click "Connect"
        N->>S: Redirect to consent screen
        S->>U: Display permissions
        U->>S: Approve
        S->>N: Return authorization code
        N->>S: Exchange for access token
        S->>N: Return token
        N->>N: Store encrypted
    ```

    ### Characteristics

    | Aspect               | Details                                    |
    | :------------------- | :----------------------------------------- |
    | **Security**         | No password sharing, industry standard     |
    | **Permissions**      | Granular control, user-approved            |
    | **Token Management** | Automatic refresh                          |
    | **Revocation**       | User can revoke anytime                    |
    | **Best For**         | User-specific actions, personal automation |

    ### Supported Services

    <CardGroup cols={3}>
      <Card title="Google" icon="mail">
        Workspace services
      </Card>

      <Card title="Microsoft" icon="building">
        365 services
      </Card>

      <Card title="Slack" icon="message-circle">
        Workspace integration
      </Card>

      <Card title="GitHub" icon="github">
        Repository access
      </Card>

      <Card title="Notion" icon="book">
        Workspace databases
      </Card>

      <Card title="LinkedIn" icon="linkedin">
        Profile and posts
      </Card>
    </CardGroup>

    <Tip>
      OAuth is the most secure method and is recommended for all services that support it.
    </Tip>
  </Tab>

  <Tab title="API Key">
    **Simple token-based authentication**

    ### How It Works

    ```mermaid theme={null}
    graph LR
        A[Generate Key in Service] --> B[Enter in Noxus]
        B --> C[Store Encrypted]
        C --> D[Use in API Requests]
    ```

    ### Characteristics

    | Aspect          | Details                              |
    | :-------------- | :----------------------------------- |
    | **Setup**       | Simple, no redirect flow             |
    | **Rotation**    | Manual rotation required             |
    | **Permissions** | Service-level permissions            |
    | **Management**  | Per-application keys                 |
    | **Best For**    | Developer tools, simple integrations |

    ### Supported Services

    <CardGroup cols={2}>
      <Card title="Airtable" icon="table">
        Personal API keys
      </Card>

      <Card title="Linear" icon="circle-dot">
        Personal API keys
      </Card>

      <Card title="OpenAI" icon="sparkles">
        Custom API keys (optional)
      </Card>

      <Card title="Anthropic" icon="bot">
        Custom API keys (optional)
      </Card>
    </CardGroup>

    <Warning>
      API keys should be rotated regularly and stored securely. Never commit them to code.
    </Warning>
  </Tab>

  <Tab title="Client ID / Access Token">
    **Pre-shared credentials from a provider's developer portal**

    ### How It Works

    ```mermaid theme={null}
    sequenceDiagram
        participant A as Admin
        participant P as Provider Admin Portal
        participant N as Noxus
        participant API as Provider API

        A->>P: Create Connected App / Private App
        A->>P: Configure scopes & permissions
        P->>A: Issue Client ID, Secret, and/or Access Token
        A->>N: Paste credentials + instance URL
        N->>API: Authenticated API requests
        API->>N: Response
    ```

    ### Characteristics

    | Aspect               | Details                                                  |
    | :------------------- | :------------------------------------------------------- |
    | **Setup**            | Manual app/integration creation in the provider's admin  |
    | **User Interaction** | None after setup — credentials are tenant-scoped         |
    | **Permissions**      | Defined when the app is created in the provider          |
    | **Token Lifetime**   | Usually long-lived; rotation is manual                   |
    | **Best For**         | Enterprise systems, providers without OAuth, custom apps |

    ### Supported Services

    <CardGroup cols={3}>
      <Card title="Salesforce" icon="cloud">
        Instance URL + Access Token
      </Card>

      <Card title="SAP" icon="building">
        Base URL + Client ID + Client Secret
      </Card>

      <Card title="Shopify" icon="shopping-bag">
        Shop Domain + Admin API Token
      </Card>

      <Card title="WhatsApp" icon="message-circle">
        Phone Number ID + Access Token
      </Card>

      <Card title="Slack (Custom App)" icon="slack">
        Bot Token + Signing Secret
      </Card>
    </CardGroup>

    <Warning>
      Static access tokens don't auto-refresh. Rotate them on a regular cadence and revoke promptly when team members leave.
    </Warning>
  </Tab>

  <Tab title="Service Principal">
    **Application-level access for Microsoft services**

    ### How It Works

    ```mermaid theme={null}
    sequenceDiagram
        participant A as Admin
        participant AZ as Azure Portal
        participant N as Noxus
        participant MS as Microsoft API
        
        A->>AZ: Register app
        A->>AZ: Configure permissions
        A->>AZ: Grant admin consent
        A->>AZ: Generate secret
        A->>N: Enter credentials
        N->>MS: Request token
        MS->>N: Return token
        N->>MS: API requests
    ```

    ### Characteristics

    | Aspect               | Details                               |
    | :------------------- | :------------------------------------ |
    | **Access Level**     | Organization-wide                     |
    | **Setup**            | Admin configuration required          |
    | **User Interaction** | None after setup                      |
    | **Permissions**      | Application permissions               |
    | **Best For**         | Background automation, cross-user ops |

    ### When to Use

    <CardGroup cols={2}>
      <Card title="Ideal Scenarios" icon="check">
        * Background automation
        * Cross-user operations
        * Scheduled tasks
        * System integrations
      </Card>

      <Card title="Requirements" icon="info">
        * Azure administrator access
        * Admin consent for permissions
        * Client secret management
        * Organization-wide scope
      </Card>
    </CardGroup>

    <Info>
      Service Principal is ideal for automated, organization-wide operations without user context.
    </Info>
  </Tab>
</Tabs>

***

## Setup Examples

<CardGroup cols={2}>
  <Card title="Google Workspace" icon="mail" href="/integrations/quick-examples#google-workspace-oauth">
    OAuth setup for Gmail, Drive, Sheets, Docs, and Calendar
  </Card>

  <Card title="Slack" icon="message-circle" href="/integrations/quick-examples#slack-oauth">
    OAuth setup for workspace channels and messaging
  </Card>

  <Card title="Airtable" icon="table" href="/integrations/quick-examples#airtable-api-key">
    API key setup for bases, tables, and records
  </Card>

  <Card title="Microsoft 365" icon="building" href="/integrations/quick-examples#microsoft-365-service-principal">
    Service Principal setup for Outlook, Teams, and SharePoint
  </Card>
</CardGroup>

***

## Security & Compliance

<CardGroup cols={2}>
  <Card title="Encryption" icon="lock">
    All credentials encrypted at rest with database-level encryption
  </Card>

  <Card title="Token Management" icon="refresh-cw">
    Automatic OAuth token refresh and secure storage
  </Card>

  <Card title="Isolation" icon="layers">
    Tokens isolated per workspace with tenant segregation
  </Card>

  <Card title="Compliance" icon="shield-check">
    SOC 2 Type II, GDPR-compliant data handling
  </Card>
</CardGroup>

***

## Best Practices

<Tabs>
  <Tab title="Development">
    * Test with sandbox accounts during development
    * Use separate credentials for dev/staging/prod
    * Handle errors gracefully with continue-on-error
    * Monitor rate limits to avoid throttling
  </Tab>

  <Tab title="Security">
    * Rotate credentials regularly
    * Audit integration access periodically
    * Remove unused integrations
    * Use read-only scopes when possible
  </Tab>

  <Tab title="Performance">
    * Cache API responses when appropriate
    * Batch requests when APIs support it
    * Use filters to reduce data transfer
    * Monitor execution time
  </Tab>
</Tabs>