# 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/marketplace/en_US/partnerLandingPage). 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.
:::

```d2
direction: down
user: "1 · IAM service user\noracle-marketplace@suger.io\n(dedicated, least-privilege)"
group: "2 · Group MarketplaceSugerIO\n+ tenancy-scoped IAM policy:\nmarketplace-offers ·\nmarketplace-publisher-family ·\nusage-record create"
key: "3 · API signing key\ndownload the private .pem\n(no passphrase) + fingerprint"
config: "Config file preview\ntenancy OCID · user OCID ·\nregion · fingerprint"
form: "4 · Suger → Integrations →\nOracle Cloud Marketplace → Connect\nAutofill from config, paste the .pem"
verify: "Suger verifies by reading your\nMarketplace Publisher listings\n(a new key can take ~2 min to replicate)"
vault: "Private key stored in Suger's\nsecret store — never shown again"
user -> group
user -> key
key -> config
config -> form: "paste + Autofill from config"
key -> form: "paste the private key"
group -> verify: "grants the read" { style.stroke-dash: 4 }
form -> verify -> vault
```

<!-- screenshot needed: (a) OCI Console → Profile → User settings → API keys → the config-file preview dialog, annotated to point out tenancy OCID / user OCID / region / fingerprint; (b) the Suger Integrations → Oracle Cloud Marketplace connect form, annotated to map each OCI value onto its Suger field. Requires a real Oracle tenancy and an authenticated Suger session. — BLOCKED: these are screens of Oracle's own OCI Console, not the Suger console, so they cannot be captured from this application; capture them from an OCI tenancy or link to Oracle's documentation instead -->

## 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/). Without it, Suger's hourly usage submissions are rejected by OCI with an authorization error. Grant it even if you do not report usage today, so metering works without a second IAM change later.
:::

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