# Integration

Grant Fours 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 Fours to sync your listings, manage private offers, and track revenue.

Fours 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 ·\nfingerprint"
form: "4 · Fours → Integrations →\nOracle Cloud Marketplace → Connect\nAutofill from config, paste the .pem"
verify: "Fours verifies by reading your\nMarketplace Publisher listings\n(a new key can take ~2 min to replicate)"
vault: "Private key stored in Fours'\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
```

## Integration Prerequisite

### 1. Create a dedicated IAM service user

Create a dedicated, least-privilege IAM user for Fours 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, Fours' 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 Fours to fill in the tenancy OCID, user OCID and fingerprint (Fours ignores the region line).

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

## Connect in Fours Console

1. Go to the **Integrations** page in the Fours 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. |
   | **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. |

   There is no Region field: Fours makes its Marketplace Publisher calls in `us-ashburn-1`, and ignores a region in a pasted configuration.

4. Click `Connect` to complete the integration. Fours 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 Fours' secret store and is never returned by the API or shown in the console again.

## Edit Integration

In the Fours console, editing the Oracle Cloud Marketplace integration changes only its **Display Name** — the credentials are write-only. To change the tenancy OCID, user OCID, fingerprint or compartment, or to rotate the API signing key, delete the integration and connect it again with the new values, or update it through the Fours API, where supplying a new private key replaces the stored one and leaving it empty keeps it.

## 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 Fours. No time window or methods to recover.

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