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

# Setup

> Connect Ravenna to Vanta using OAuth 2.0 from the integrations settings to enable automated user data sync for SOC 2 compliance reporting.

<Info>Connect to Vanta using OAuth 2.0 for secure user data synchronization</Info>

This guide walks you through connecting Ravenna to Vanta to enable automated compliance monitoring and user data synchronization.

## Prerequisites

Before you begin, ensure you have:

* Vanta account with admin access
* Ravenna organization admin privileges
* Access to create OAuth applications in Vanta

## Setup guide

### Connect via OAuth

The Vanta integration uses OAuth 2.0 for secure authentication. No manual configuration is required.

<Steps>
  <Step title="Navigate to integrations">
    1. Go to **Settings > Integrations**
    2. Find **Vanta** in the Compliance Management section
  </Step>

  <Step title="Select Vanta">
    Click **Connect** on the Vanta integration card
  </Step>

  <Step title="Authorize with Vanta">
    You'll be redirected to Vanta to authorize the connection:

    1. Sign in to your Vanta account
    2. Review the requested permissions:
       * **Read resources**: Access to view previously synced data
       * **Write resources**: Permission to push user account information
    3. Click **Authorize** to grant access

    <Note>
      Ravenna will only sync user data to Vanta. No data is pulled from Vanta back to Ravenna.
    </Note>
  </Step>

  <Step title="Complete setup">
    After authorization, you'll be redirected back to Ravenna:

    1. The integration will validate the OAuth connection
    2. Initial user sync will begin automatically
    3. Subsequent syncs occur every 24 hours

    <Info>
      The initial sync may take a few minutes depending on your organization size.
    </Info>
  </Step>
</Steps>

## What gets synced

### User information

The integration syncs the following data for each verified user:

<ParamField path="uniqueId" type="string">
  Ravenna user ID (internal database ID)
</ParamField>

<ParamField path="displayName" type="string">
  User's full name (first name + last name)
</ParamField>

<ParamField path="email" type="string">
  Primary email address
</ParamField>

<ParamField path="role" type="string">
  Organization role (ADMIN, MEMBER, GUEST, etc.)
</ParamField>

<ParamField path="mfaEnabled" type="boolean">
  Whether multi-factor authentication is enabled
</ParamField>

<ParamField path="mfaMethods" type="array">
  List of enrolled MFA methods (e.g., `["totp", "sms"]`)
</ParamField>

<ParamField path="passwordEnabled" type="boolean">
  Whether password authentication is enabled
</ParamField>

<ParamField path="authMethods" type="array">
  Authentication providers (e.g., `["auth0", "google-oauth2"]`)
</ParamField>

<ParamField path="emailVerified" type="boolean">
  Whether the user's email has been verified
</ParamField>

<ParamField path="createdAt" type="datetime">
  Account creation timestamp
</ParamField>

### Filtered users

The following users are **not** synced to Vanta:

* Users who haven't verified their email (pending invitations)
* Bot accounts
* Users without email addresses
* Deleted or suspended accounts

## Sync schedule

<Info>
  User data automatically syncs to Vanta **every 24 hours** to keep compliance data current.
</Info>

The sync runs as a background workflow and includes:

1. Fetching organization members from Ravenna
2. Enriching data with authentication and MFA information
3. Filtering out bot accounts and unverified users
4. Pushing updated user list to Vanta

## Disconnecting the integration

When you disconnect the Vanta integration:

1. **Token revocation**: Ravenna automatically calls Vanta's token suspension API
2. **Vanta cleanup**: The integration is disconnected in your Vanta account
3. **Access revoked**: OAuth tokens are revoked and can no longer be used
4. **Data retention**: Previously synced user data remains in Vanta according to their retention policies

<Warning>
  Disconnecting the integration stops future data syncs but does not delete historical data from Vanta. You can remove the integration and historical data via the Vanta app.
</Warning>

To disconnect:

1. Go to **Settings > Integrations**
2. Find the Vanta integration
3. Click **Disconnect**
4. Confirm the disconnection

## Troubleshooting

<AccordionGroup>
  <Accordion title="OAuth authorization failed" icon="circle-x">
    **Cause**: OAuth flow was cancelled or failed

    **Solution**:

    * Ensure you have admin access to your Vanta account
    * Try connecting again from Settings > Integrations
    * Clear browser cookies and try again
    * Check if popup blockers are preventing the OAuth window
  </Accordion>

  <Accordion title="Users not appearing in Vanta" icon="user-x">
    **Cause**: Users may not meet sync criteria

    **Solution**:

    * Verify users have verified their email addresses
    * Check that users are not bot accounts
    * Wait for the next 24-hour sync cycle
    * Ensure users have valid email addresses
    * Check Vanta dashboard after 5-10 minutes for sync delay
  </Accordion>

  <Accordion title="Sync errors in logs" icon="triangle-alert">
    **Cause**: API errors or connectivity issues

    **Solution**:

    * Check integration status in Settings > Integrations
    * Verify OAuth tokens are still valid
    * Try disconnecting and reconnecting the integration
    * Contact support if errors persist
  </Accordion>

  <Accordion title="Token suspension failed during disconnect" icon="ban">
    **Cause**: OAuth token may already be revoked or invalid

    **Solution**:

    * Try disconnecting again (Vanta returns 200 for already-revoked tokens)
    * If disconnect continues to fail, check for network issues
    * Contact support if issue persists
  </Accordion>

  <Accordion title="Integration shows as connected but not syncing" icon="unplug">
    **Cause**: Workflow scheduling issue or OAuth token expired

    **Solution**:

    * Check OAuth token expiration in integration settings
    * Disconnect and reconnect to refresh OAuth tokens
    * Verify organization has users that meet sync criteria
    * Check application logs for sync errors
  </Accordion>
</AccordionGroup>

## Security and privacy

<Info>
  The Vanta integration follows security best practices:
</Info>

* **OAuth 2.0**: Secure authorization without sharing passwords
* **Limited scope**: Only requests necessary permissions for user sync
* **Token encryption**: OAuth tokens are encrypted at rest in Ravenna's database
* **Automatic revocation**: Tokens are revoked when disconnecting
* **Audit logging**: All sync operations are logged for security auditing

### Data flow

```text wrap theme={"system"}
Ravenna → Vanta (one-way sync)
```

1. The integration fetches your Ravenna user account data
2. Enriches data with authentication methods and MFA information
3. Filters users based on verification status and account type
4. Pushes data to Vanta via OAuth-authenticated API call
5. Vanta stores data for compliance monitoring

<Warning>
  This is a **one-way** integration. Ravenna does not receive any data from Vanta.
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="How often does user data sync?" icon="clock">
    User data syncs automatically every 24 hours. The sync schedule ensures compliance data stays current without overwhelming Vanta's API.
  </Accordion>

  <Accordion title="Can I manually trigger a sync?" icon="refresh-cw">
    Manual sync is not currently available. The automated 24-hour schedule is designed to balance data freshness with API rate limits.
  </Accordion>

  <Accordion title="What happens to synced data if I disconnect?" icon="unlink">
    Disconnecting stops future syncs but does not delete historical data from Vanta. Previously synced user data remains in Vanta according to their retention policies. Contact Vanta support to request data deletion.
  </Accordion>

  <Accordion title="Why are some users not syncing?" icon="user-x">
    Users are excluded from sync if they haven't verified their email, are bot accounts, or don't have a valid email address. Check the user's email verification status in Ravenna.
  </Accordion>

  <Accordion title="Can I sync custom user attributes?" icon="list-check">
    Currently, the integration syncs standard user attributes (name, email, role, MFA status, authentication methods). Custom attributes are not supported at this time.
  </Accordion>

  <Accordion title="How do I update OAuth permissions?" icon="key">
    Disconnect the integration and reconnect to re-authorize with updated OAuth scopes. This will grant any new permissions required by Vanta.
  </Accordion>
</AccordionGroup>