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

# OVH Cloud

> Connect Aurora to your OVH Cloud account using OAuth 2.0 or API credentials

## Overview

Aurora integrates with OVH Cloud using OAuth 2.0 authorization code flow for a streamlined user experience, or legacy API credentials (Application Key, Application Secret, Consumer Key) for advanced users.

## What Aurora Can Access

Once authenticated, Aurora can discover and manage:

* **Public Cloud Instances**: Virtual machines in OVH Public Cloud
* **Managed Kubernetes**: OVH Managed Kubernetes Service clusters
* **Managed Databases**: PostgreSQL, MySQL, MongoDB, Redis databases
* **Load Balancers**: OVH Load Balancer as a Service
* **Container Registries**: Private Docker registries
* **Private Networks**: vRack private networking
* **Dedicated Servers**: Bare metal servers (account-level)
* **Object Storage**: S3-compatible object storage
* **Cloud Projects**: OVH Public Cloud projects

## Prerequisites

<Steps>
  <Step title="OVH Account">
    You need an OVH Cloud account (EU, US, or CA region)
  </Step>

  <Step title="Public Cloud Project">
    At least one Public Cloud project for cloud resources (instances, Kubernetes, etc.)
  </Step>

  <Step title="Payment Method">
    Active payment method for resource provisioning
  </Step>
</Steps>

## Environment Variables

Configure these environment variables in Aurora's `.env` file for OAuth flow:

```bash theme={null}
# OVH OAuth2 Client Credentials (per region)
OVH_EU_CLIENT_ID=your-ovh-eu-oauth2-client-id
OVH_EU_CLIENT_SECRET=your-ovh-eu-oauth2-client-secret
OVH_EU_REDIRECT_URI=https://your-aurora-backend.com/ovh/oauth2/callback

OVH_US_CLIENT_ID=your-ovh-us-oauth2-client-id
OVH_US_CLIENT_SECRET=your-ovh-us-oauth2-client-secret
OVH_US_REDIRECT_URI=https://your-aurora-backend.com/ovh/oauth2/callback

OVH_CA_CLIENT_ID=your-ovh-ca-oauth2-client-id
OVH_CA_CLIENT_SECRET=your-ovh-ca-oauth2-client-secret
OVH_CA_REDIRECT_URI=https://your-aurora-backend.com/ovh/oauth2/callback

# Frontend URL
FRONTEND_URL=https://your-aurora-frontend.com
```

<Warning>
  OVH OAuth2 requires region-specific client credentials. You must create separate OAuth2 applications for each OVH region (EU, US, CA) you want to support.
</Warning>

## Authentication Methods

Aurora supports two authentication methods for OVH:

### 1. OAuth 2.0 Authorization Code Flow (Recommended)

**User Experience**: "Sign in with OVH" button - simple, 5 steps, \~30 seconds

**Benefits**:

* Streamlined user experience (no copy/paste)
* Automatic token refresh
* Secure credential storage
* Similar to "Sign in with Google"

**Flow**:

1. User clicks "Connect with OVH"
2. Redirected to OVH login page
3. User authorizes Aurora
4. Redirected back with access + refresh tokens
5. Tokens stored securely in Vault

### 2. API Credentials (Legacy/Advanced)

**User Experience**: Manual credential creation - 14 steps, \~2 minutes, 3 copy/paste operations

**Benefits**:

* Full control over permissions
* Works without OAuth app registration
* Suitable for automation scripts

**Flow**:

1. Create application at OVH developer portal
2. Generate consumer key with specific permissions
3. Validate consumer key via browser
4. Copy credentials to Aurora

## OAuth 2.0 Setup (Recommended)

<Note>
  OVH's OAuth 2.0 authorization endpoints are working and stable as of January 2025, but are not yet officially documented by OVH. Third-party implementations confirm functionality.
</Note>

### Step 1: Create OAuth2 Application at OVH

<Steps>
  <Step title="Log in to OVH API Console">
    Go to the OVH API Console for your region:

    * EU: [https://eu.api.ovh.com/console/](https://eu.api.ovh.com/console/)
    * US: [https://api.us.ovhcloud.com/console/](https://api.us.ovhcloud.com/console/)
    * CA: [https://ca.api.ovh.com/console/](https://ca.api.ovh.com/console/)
  </Step>

  <Step title="Navigate to OAuth2 Client Creation">
    Use the API endpoint: `POST /me/api/oauth2/client`
  </Step>

  <Step title="Create OAuth2 Client">
    Provide:

    * **name**: `Aurora Integration`
    * **description**: `Aurora cloud management platform`
    * **flow**: `AUTHORIZATION_CODE`
    * **callbackUrls**: `["https://your-aurora-backend.com/ovh/oauth2/callback"]`
  </Step>

  <Step title="Save Client Credentials">
    Copy the returned `clientId` and `clientSecret` to your `.env` file
  </Step>

  <Step title="Repeat for Other Regions">
    If you use multiple OVH regions, create separate OAuth2 clients for each
  </Step>
</Steps>

### Step 2: Connect Aurora

<Steps>
  <Step title="Open Aurora UI">
    Navigate to OVH integration page
  </Step>

  <Step title="Select Region">
    Choose your OVH region: EU, US, or CA
  </Step>

  <Step title="Click Connect with OVH">
    Aurora generates authorization URL and redirects you to OVH
  </Step>

  <Step title="Authorize Aurora">
    Log in to OVH and grant Aurora the requested permissions (scope: `all`)
  </Step>

  <Step title="Redirected Back">
    OVH redirects back to Aurora with authorization code
  </Step>

  <Step title="Token Exchange">
    Aurora exchanges code for access + refresh tokens and stores them in Vault
  </Step>

  <Step title="Optional: IAM Policy">
    For least-privilege access, Aurora can create an IAM policy scoped to your project
  </Step>
</Steps>

## API Credentials Setup (Legacy)

<Accordion title="Show Legacy API Credentials Setup">
  ### Step 1: Create OVH Application

  <Steps>
    <Step title="Go to OVH Token Creation Page">
      Visit the token creation page for your region:

      * EU: [https://eu.api.ovh.com/createToken/](https://eu.api.ovh.com/createToken/)
      * US: [https://api.us.ovhcloud.com/createToken/](https://api.us.ovhcloud.com/createToken/)
      * CA: [https://ca.api.ovh.com/createToken/](https://ca.api.ovh.com/createToken/)
    </Step>

    <Step title="Fill Application Details">
      * **Application name**: `Aurora`
      * **Application description**: `Aurora cloud management`
      * **Validity**: `Unlimited` (recommended)
    </Step>

    <Step title="Set Access Rights">
      Grant permissions:

      ```
      GET  /cloud/*
      POST /cloud/*
      PUT  /cloud/*
      DELETE /cloud/*
      GET  /me
      POST /me/api/oauth2/client
      POST /iam/policy
      ```
    </Step>

    <Step title="Create Keys">
      Click **Create keys**
    </Step>

    <Step title="Save Credentials">
      Copy the following:

      * **Application Key** (AK)
      * **Application Secret** (AS)
      * **Consumer Key** (CK) - after validation
    </Step>

    <Step title="Validate Consumer Key">
      Click the validation link to authorize the consumer key
    </Step>
  </Steps>

  ### Step 2: Connect Aurora with API Credentials

  <Steps>
    <Step title="Open Aurora UI">
      Navigate to OVH integration settings
    </Step>

    <Step title="Choose API Credentials Method">
      Select "Use API credentials" option
    </Step>

    <Step title="Enter Credentials">
      Provide:

      * **Endpoint**: `ovh-eu`, `ovh-us`, or `ovh-ca`
      * **Application Key**: From Step 1
      * **Application Secret**: From Step 1
      * **Consumer Key**: From Step 1
    </Step>

    <Step title="Validate Connection">
      Aurora will call `/me` API to verify credentials
    </Step>

    <Step title="Optional: Create Service Account">
      Aurora can create an OAuth2 service account (client credentials flow) for long-term access
    </Step>
  </Steps>
</Accordion>

## OAuth 2.0 Flow Details

### Authorization Request

Aurora generates an authorization URL:

```
https://www.ovh.com/auth/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-aurora-backend.com/ovh/oauth2/callback&
  response_type=code&
  scope=all&
  state=CSRF_TOKEN&
  code_challenge=PKCE_CHALLENGE&
  code_challenge_method=S256
```

**Security Features**:

* **State parameter**: CSRF protection (validated on callback)
* **PKCE**: Proof Key for Code Exchange (S256 method)
* **Scope**: `all` (full API access)

### Token Exchange

After user authorization, OVH redirects to callback with authorization code:

```http theme={null}
POST https://www.ovh.com/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https://your-aurora-backend.com/ovh/oauth2/callback&
code_verifier=PKCE_VERIFIER
```

**Response**:

```json theme={null}
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### Token Refresh

Access tokens expire after 1 hour. Aurora automatically refreshes them:

```http theme={null}
POST https://www.ovh.com/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET
```

## IAM Policy (Least Privilege)

For OAuth2 service accounts, Aurora can create IAM policies to restrict access:

```python theme={null}
# Example IAM policy for a service account
{
  "name": "Aurora-User-123-Policy",
  "description": "Aurora policy for user 123",
  "identities": ["urn:v1:eu:identity:credential:NIC-HANDLE/oauth2-CLIENT_ID"],
  "resources": [{"urn": "urn:v1:eu:resource:publicCloudProject:PROJECT_ID"}],
  "permissions": {
    "allow": [
      {"action": "publicCloudProject:apiovh:instance/*"},
      {"action": "publicCloudProject:apiovh:network/*"},
      {"action": "publicCloudProject:apiovh:volume/*"},
      {"action": "publicCloudProject:apiovh:kube/*"}
    ]
  }
}
```

This restricts the service account to:

* Instances (VMs)
* Networking
* Storage volumes
* Kubernetes clusters

Within a specific project.

## API Endpoints

### Initiate OAuth2 Flow

```http theme={null}
POST /ovh/oauth2/initiate
Content-Type: application/json

{
  "endpoint": "ovh-eu",
  "projectId": "optional-project-id"
}
```

Returns authorization URL for user redirect.

### OAuth2 Callback

```http theme={null}
GET /ovh/oauth2/callback?code=AUTH_CODE&state=STATE_TOKEN
```

Handles OAuth redirect, exchanges code for tokens.

### Refresh Token

```http theme={null}
POST /ovh/oauth2/refresh
Headers: X-User-ID: your-user-id
```

Refreshes expired access token using refresh token.

### Validate API Credentials

```http theme={null}
POST /ovh/validate-credentials
Content-Type: application/json

{
  "endpoint": "ovh-eu",
  "applicationKey": "...",
  "applicationSecret": "...",
  "consumerKey": "..."
}
```

Validates legacy API credentials.

## Resource Discovery

Aurora discovers OVH resources using the `ovhcloud` CLI:

### Cloud Project Resources

* **Instances**: `ovhcloud cloud instance list --service-name PROJECT_ID`
* **Kubernetes**: `ovhcloud cloud kube list --service-name PROJECT_ID`
* **Databases**: `ovhcloud cloud database-service list --service-name PROJECT_ID`
* **Load Balancers**: `ovhcloud cloud loadbalancer list --service-name PROJECT_ID`
* **Container Registries**: `ovhcloud cloud container-registry list --service-name PROJECT_ID`
* **Private Networks**: `ovhcloud cloud network private list --service-name PROJECT_ID`

### Account-Level Resources

* **Dedicated Servers**: `ovhcloud baremetal list`

## Troubleshooting

### Invalid OAuth State Token

**Error**: "Invalid or expired state token"

**Solution**:

* State tokens expire after 10 minutes
* Re-initiate the OAuth flow
* Ensure cookies are enabled (if using session storage)
* Check Redis connectivity for state cache

### Token Exchange Failed

**Error**: "Token exchange failed: invalid\_grant"

**Solution**:

* Authorization codes are single-use only
* If you refresh the callback page, you'll get this error
* Re-initiate the OAuth flow to get a new authorization code
* Check that `redirect_uri` matches exactly (including trailing slash)

### No Access Token in Response

**Error**: "No access\_token received from OVH"

**Solution**:

* Check OVH API status page for outages
* Verify OAuth2 client credentials are correct
* Ensure client has `AUTHORIZATION_CODE` flow enabled
* Review OVH API logs for detailed error messages

### Refresh Token Not Provided

**Warning**: "No refresh token received - user may need to re-authorize after expiration"

**Context**: OVH may not always provide refresh tokens. This is expected behavior.

**Solution**:

* Users will need to re-authenticate when access tokens expire (\~1 hour)
* Consider requesting offline access scope if available
* For automation, use client credentials flow instead

### Invalid API Credentials

**Error**: "Invalid credentials. Please check your consumer key and permissions."

**Solution**:

1. Verify Application Key, Application Secret, and Consumer Key are correct
2. Ensure Consumer Key was validated via the OVH validation link
3. Check that credentials haven't expired (if time-limited)
4. Verify permissions include `/me` read access

### IAM Policy Creation Failed

**Error**: "IAM policy creation error"

**Solution**:

* Ensure your account has IAM policy creation permissions
* Verify project ID is correct
* Check that the region matches your endpoint (EU, US, CA)
* Review OVH IAM documentation for policy format requirements

### CLI Command Failures

**Error**: Resource discovery commands timeout or fail

**Solution**:

1. Verify `ovhcloud` CLI is installed and configured
2. Check network connectivity to OVH API endpoints
3. Ensure service account has permissions for the resource type
4. Try running the command manually to see detailed errors:
   ```bash theme={null}
   ovhcloud cloud instance list --service-name PROJECT_ID --json
   ```

## Security Considerations

* **OAuth Tokens**: Access and refresh tokens stored in Vault with encryption
* **PKCE**: Code challenge prevents authorization code interception
* **State Parameter**: CSRF protection for OAuth flow
* **Client Secrets**: Never expose in client-side code
* **Token Expiration**: Access tokens expire after 1 hour
* **IAM Policies**: Restrict service accounts to specific projects/actions
* **Audit**: Monitor OVH audit logs for actions performed by Aurora

## OVH Regions

* **ovh-eu**: Europe ([www.ovh.com](http://www.ovh.com))
* **ovh-us**: United States (us.ovhcloud.com)
* **ovh-ca**: Canada (ca.ovh.com)

Each region requires separate OAuth2 client credentials.

## Token Storage

OVH tokens are stored in Vault with:

* **Provider**: `ovh`
* **Endpoint**: Region identifier (`ovh-eu`, `ovh-us`, `ovh-ca`)
* **Access Token**: Bearer token for API calls
* **Refresh Token**: Long-lived token for obtaining new access tokens (if provided)
* **Client ID**: Stored for IAM validation
* **Expires At**: Unix timestamp for token expiration
* **Auth Method**: `authorization_code` or `api_credentials`

## Next Steps

After connecting OVH:

1. Aurora will discover your OVH infrastructure
2. View discovered resources in the Aurora dashboard
3. Use Aurora's AI agent to manage OVH resources
4. Deploy applications to Managed Kubernetes clusters
5. Manage VMs and databases across projects
6. Monitor costs and optimize resource usage