> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/integrations/openai.md).

# OpenAI

Configure the OpenAI integration in Pharos Admin for AI Issue Analysis and Org Genie.

The OpenAI integration powers Pharos's AI capabilities — **AI Issue Analysis** and **Org Genie**. Once connected, Pharos can analyze issues for root cause, severity, resolution steps, and impact, and you can use Org Genie's natural language interface to investigate errors, correlate metadata changes, and generate insights from your observability data.

{% hint style="info" %}
OpenAI is a **prerequisite** for both [AI Issue Analysis](https://docs.pharos.ai/configuration-guide/issue-tracker.md) and Org Genie. Without it, the Issue Tracker page will prompt you to enable OpenAI before any AI features become available.
{% endhint %}

***

## Accessing OpenAI Settings

1. Open the **Pharos** app → **Pharos Admin**
2. Select **Integrations** from the left-hand menu
3. Click **OpenAI**

Before configuration, the page shows the **Enable OpenAI Integration** toggle in the off state:

![OpenAI Settings — disabled state](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-f1babec2c95a06d0343cf5c835a915b1ad8d6016%2Fopenai-disabled.png?alt=media)

***

## Prerequisites

Pharos asks you to supply **your own OpenAI API key** — that is the default. If you do not have an OpenAI account, **Pharos can provide a key on request**: email <success@pharos.ai>.

{% hint style="info" %}
Requesting a key from Pharos is available on **any Pharos edition** — there is no edition requirement.
{% endhint %}

Both paths are fully supported, and inside Pharos they are identical — the same screen, the same field, the same setup. They differ only in where the key comes from and who is billed by OpenAI. You can move from one to the other later; see [Rotating or Replacing the Key](#rotating-or-replacing-the-key).

| Path                       | How you get the key                                           | Who is billed by OpenAI                  |
| -------------------------- | ------------------------------------------------------------- | ---------------------------------------- |
| **Your own key** (default) | Create it in your OpenAI account — see the requirements below | You, directly                            |
| **A Pharos-provided key**  | Email <success@pharos.ai>. Nothing to set up on OpenAI's side | Pharos — you are not charged for the key |

### Requirements for Your Own Key

These apply **only if you are bringing your own key**. On a Pharos-provided key, none of them apply — go straight to [Configuration](#configuration).

| Requirement            | Details                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **OpenAI account**     | Sign up at [platform.openai.com](https://platform.openai.com)                                                                                                      |
| **API key**            | A secret key from your OpenAI account ([API Keys](https://platform.openai.com/api-keys))                                                                           |
| **Billing configured** | OpenAI requires a funded account for API usage — add a payment method in the [Billing](https://platform.openai.com/settings/organization/billing/overview) section |

***

## Configuration

{% stepper %}
{% step %}

### 1. Get an OpenAI API Key

If **Pharos provided your key**, you already have it — skip to step 2.

If you are **bringing your own key**:

1. Log in to [platform.openai.com](https://platform.openai.com)
2. Navigate to **API keys** (under your account or organization settings)
3. Click **Create new secret key**
4. Give it a meaningful name (e.g., "Pharos Production")
5. Copy the key immediately — you won't be able to view it again
   {% endstep %}

{% step %}

### 2. Enable the Integration and Enter the Key

In Pharos Admin → Integrations → OpenAI:

1. Turn on the **Enable OpenAI Integration** toggle
2. Paste the API key into the **Token** field — that is the admin screen's label for the OpenAI API key
3. Click **Save**

![OpenAI Settings — enabled with the API key configured](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-49c373df4a9ed56139bac0781db3fffe051eaf5c%2Fopenai-enabled.png?alt=media)
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Treat the key as a credential.** It authorizes API usage on whichever OpenAI account issued it. Never commit it to version control or share it publicly. Pharos stores it in a protected custom setting, which subscriber-org code and other packages cannot read.

If the key is compromised: on **your own key**, revoke it immediately in the [OpenAI dashboard](https://platform.openai.com/api-keys) and generate a new one; on **a Pharos-provided key**, email <success@pharos.ai> straight away for a replacement.
{% endhint %}

***

## What OpenAI Enables

Once the integration is active, two AI-powered features become available:

### AI Issue Analysis

Pharos can automatically analyze issues for:

* **Root cause** — what caused the error
* **Severity assessment** — how critical is this problem
* **Resolution steps** — suggested actions to fix it
* **Impact analysis** — what users and processes are affected
* **Plain-language explanation** — accessible summary for non-technical stakeholders

AI Issue Analysis is configured separately in the [Issue Tracker](https://docs.pharos.ai/configuration-guide/issue-tracker.md) page, where you set up Platform Events for asynchronous communication between Pharos's cloud and your Salesforce org.

### Org Genie

A conversational AI interface grounded in your org's data — logs, issues, and metadata changes. Ask natural language questions like:

* *"What are the highest priority issues in the last 30 days?"*
* *"What changed when this error started?"*
* *"Which issues occurred in the last week?"*

{% hint style="success" %}
**For best results with Org Genie**, also enable [GitHub](https://docs.pharos.ai/configuration-guide/integrations/github.md) + [Change Tracking](https://docs.pharos.ai/configuration-guide/change-tracking.md). Without Change Tracking, Org Genie can only answer questions about logs and issues — not about your metadata or recent org changes.
{% endhint %}

***

## Usage and Billing

**Pharos does not charge for AI features.** The two key paths differ only in who is billed by OpenAI.

### On Your Own Key

* **You pay OpenAI directly** for API usage
* **Usage depends on** query volume, response length, and the model used
* **Monitor usage** in the [OpenAI Usage dashboard](https://platform.openai.com/usage) to track spending
* **Set spending limits** in OpenAI's [Billing settings](https://platform.openai.com/settings/organization/billing/overview) to avoid unexpected charges

### On a Pharos-Provided Key

* **No OpenAI bill and no usage dashboard on your side** — the OpenAI account is Pharos's
* **Pharos does not charge you** for the provided key
* **Questions about usage or limits** go to <success@pharos.ai>

**On both paths**, initial indexing for Org Genie may have higher one-time usage; subsequent queries are incremental.

***

## Data Privacy

Pharos operates a trust layer — your business data stays within your control. What goes to OpenAI is error messages, stack traces, metadata structure, and aggregated statistics; raw record data, transaction details, and restricted fields do not. Your data is never used to train external models.

For the itemized boundary, see [Security & Data Access](https://docs.pharos.ai/configuration-guide/security.md#ai-data-handling) — the page to hand an information security reviewer.

***

## Prerequisites for Best Results

| Prerequisite                            | Why                                                                                                                                               |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitHub + Change Tracking**            | Enables metadata correlation — Org Genie can answer "what changed when this error started?"                                                       |
| **AI Issue Analysis (Platform Events)** | Configure in [Issue Tracker](https://docs.pharos.ai/configuration-guide/issue-tracker.md) to enable asynchronous AI analysis of individual issues |
| **Historical data**                     | Allow 1–2 weeks for logs and metadata to accumulate for meaningful trend analysis                                                                 |
| **Indexing time**                       | Org Genie indexes data in the background; allow approximately 1 hour for initial indexing to complete                                             |

***

## Rotating or Replacing the Key

To rotate the API key, or to replace one key with another:

1. Have the replacement key to hand — on your own key, generate one in the [OpenAI dashboard](https://platform.openai.com/api-keys); on a Pharos-provided key, request a replacement from <success@pharos.ai>
2. In Pharos Admin → Integrations → OpenAI, replace the value in the **Token** field
3. Click **Save**
4. If the old key is yours, revoke it in OpenAI for security

{% hint style="info" %}
**Moving from a Pharos-provided key to your own** is the same operation as a rotation — paste your key into the **Token** field and save. There is no reconfiguration and no data migration. Let <success@pharos.ai> know so the provided key can be retired.
{% endhint %}

***

## Troubleshooting

| Issue                                     | Cause                                                | Resolution                                                                                                                                                                                                           |
| ----------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Invalid API key"                         | Key incorrect, revoked, or expired                   | Verify it's copied correctly with no extra whitespace. On your own key, generate a new one; on a Pharos-provided key, contact <success@pharos.ai>                                                                    |
| "Rate limit exceeded"                     | Too many requests in a short period                  | Reduce query frequency. On your own key, check your [rate limits](https://platform.openai.com/docs/guides/rate-limits) in OpenAI; on a Pharos-provided key, contact <success@pharos.ai>                              |
| "Insufficient quota"                      | The OpenAI account behind the key is out of credits  | On your own key, add a payment method or credits in the [OpenAI Billing](https://platform.openai.com/settings/organization/billing/overview) dashboard; on a Pharos-provided key, contact <success@pharos.ai>        |
| Key saved, but AI analysis never returns  | Saving doesn't always catch a key that can't be used | Re-check the key for extra whitespace or truncation and save again; if analysis still doesn't run, contact <success@pharos.ai>                                                                                       |
| Issue Tracker still says "enable OpenAI"  | Integration saved but not enabled                    | Verify the toggle is on and the key is saved; refresh the Issue Tracker page                                                                                                                                         |
| Org Genie returns no results              | Indexing incomplete or no data                       | Wait for indexing (\~1 hour); ensure logs and issues exist in the org                                                                                                                                                |
| Org Genie can't answer metadata questions | Change Tracking not enabled                          | Enable [GitHub](https://docs.pharos.ai/configuration-guide/integrations/github.md) + [Change Tracking](https://docs.pharos.ai/configuration-guide/change-tracking.md); allow time for metadata history to accumulate |

***

## Related

* [Issue Tracker (AI Issue Analysis)](https://docs.pharos.ai/configuration-guide/issue-tracker.md) — Configure Platform Events for asynchronous AI analysis
* [GitHub Integration](https://docs.pharos.ai/configuration-guide/integrations/github.md) — Connect your repository for metadata version control
* [Change Tracking](https://docs.pharos.ai/configuration-guide/change-tracking.md) — Enable hourly metadata snapshots for AI correlation
* [OpenAI API Keys](https://platform.openai.com/api-keys) — Manage your API keys
* [OpenAI Usage Dashboard](https://platform.openai.com/usage) — Monitor API consumption and costs
