# Integration

Grant Suger the necessary access to manage your Oracle Cloud Marketplace on your behalf, no more no less.

---

## Overview

To sell on Oracle Cloud Marketplace, you first need to be an approved Oracle Cloud Marketplace publisher. Publishing requires an Oracle Cloud account and an approved publisher profile in the [Oracle Cloud Marketplace Partner Portal](https://cloudmarketplace.oracle.com/partner). More details can be found in the [Oracle Cloud Marketplace publisher documentation](https://docs.oracle.com/en-us/iaas/Content/Marketplace/overview.htm).

Once you are a publisher with listings in your Oracle Cloud (OCI) tenancy, you can integrate with Suger to sync your listings, manage private offers, and track revenue.

Suger authenticates to OCI with an **API signing key** of an IAM user in your tenancy — the same key-based authentication used by the OCI CLI and SDKs.

:::note
**Org-Level only.** Oracle Cloud Marketplace connects with an organization-wide OCI API signing key and does not support user-level integrations.
:::

## Integration Prerequisite

### 1. Create a dedicated IAM service user

Create a dedicated, least-privilege IAM user for Suger named `oracle-marketplace@suger.io`. Do not use a personal or administrator account. See [Managing Users](https://docs.oracle.com/en-us/iaas/Content/Identity/users/about-managing-users.htm) in the OCI documentation.

### 2. Grant Marketplace Publisher permissions

Add the `oracle-marketplace@suger.io` user to a group named `MarketplaceSugerIO` and create an IAM policy that grants the group access to Marketplace Publisher resources, private offers, and usage records:

```
Allow group MarketplaceSugerIO to manage marketplace-offers in tenancy
Allow group MarketplaceSugerIO to manage marketplace-publisher-family in tenancy
Allow group MarketplaceSugerIO to {MARKETPLACE_SELF_SUBSCRIPTION_USAGE_RECORD_CREATE} in tenancy
```

:::note
The usage-record permission is required for [Oracle usage metering](/oracle-marketplace/usage-metering/). Metering is built into Suger, but the hourly submission to OCI is **currently paused** and does not report or bill usage yet — today's Oracle offers bill as one-time contract value only. Granting the permission now means metering can be enabled later without editing your IAM policy again.
:::

:::note
Private offers exist at the **tenancy** level, so these statements must be scoped to the tenancy, not to a compartment. See Oracle's [Required IAM Policies for private offers](https://docs.oracle.com/en-us/iaas/Content/Marketplace/privateoffers-required-iam-policies.htm) and [Marketplace Publisher IAM policy reference](https://docs.oracle.com/en-us/iaas/Content/Marketplace/publisher-iam-policy.htm).
:::

### 3. Add an API signing key to the service user

Follow the [official guideline](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm) to add an API key:

1. In the OCI Console, go to **Profile → User settings → API keys → Add API key** (for the service user).
2. Generate a key pair and **download the private key** (`.pem` file). Keep it safe — OCI does not show it again.
3. Note the key **fingerprint** and the **configuration file preview** shown after the key is added. The preview contains the user OCID, tenancy OCID, region, and fingerprint — you can paste it into Suger to auto-fill the form.

:::note
**Encrypted (passphrase-protected) private keys are not supported yet.** Generate the key without a passphrase.
:::

## Connect in Suger Console

1. Go to the **Integrations** page in the Suger console and click `Connect` on the **Oracle Cloud Marketplace** integration.

2. (Optional) Paste the **configuration file preview** from the OCI Console into the *Quick fill from OCI config* box and click `Autofill from config`. Both the `[DEFAULT]` config-file format and a JSON object are accepted.

3. Fill in the remaining fields:

   | Field | Description |
   |---|---|
   | **Tenancy OCID** | The OCID of your Oracle Cloud tenancy (Console → Profile → Tenancy). |
   | **User OCID** | The OCID of the dedicated IAM service user created above. |
   | **Region** | The OCI region identifier used for Marketplace Publisher calls, e.g. `us-ashburn-1`. |
   | **API Key Fingerprint** | The fingerprint of the public API signing key uploaded to the user. |
   | **API Signing Private Key (PEM)** | The downloaded private key. Paste it or load it from the `.pem` file. |
   | **Compartment OCID** (optional) | Scopes catalog reads to a compartment. Leave empty to use the tenancy root — recommended, especially when transacting private offers. |

4. Click `Connect` to complete the integration. Suger verifies the credentials by reading your Marketplace Publisher listings.

:::note
A freshly created user or API key can take ~2 minutes to replicate inside OCI before verification succeeds. If verification fails right after creating the key, wait a moment and retry.
:::

The private key is stored in Suger's secret store and is never returned by the API or shown in the console again.

## Edit Integration

The Oracle Cloud Marketplace integration can be edited in place. You can update the identity fields (tenancy OCID, user OCID, region, fingerprint, compartment) at any time. To rotate the API signing key, supply a new private key; leaving the private key field empty keeps the existing stored key.

## Delete Integration

The Oracle Cloud Marketplace integration can be deleted like all other integrations. Once the deletion is triggered, all integration info including the **API signing private key** is deleted immediately & permanently from Suger. No time window or methods to recover.

:::warning
Deleting the integration may affect active marketplace offers and entitlements synced from Oracle.
:::