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

# Cloudsmith

> Connect your Cloudsmith workspace to Oleria to discover who can reach your package repositories: members, teams, roles, service accounts, entitlement tokens, repository privileges and the audit log.

Cloudsmith is a cloud-native package and artifact registry. Connect your Cloudsmith workspace to Oleria to see every person and machine that can read or publish packages, through which privilege, and what they did.

## What Oleria discovers

Oleria reads your Cloudsmith workspace through the Cloudsmith REST API (`https://api.cloudsmith.io/v1`) on its [regular sync schedule](/integrations/overview#sync-model):

* **Users** - workspace members with their workspace role (Owner, Manager, Member, Collaborator), email, active state, join date and last login. Two-factor status per user, and SSO status from the workspace's SAML settings. Collaborators are marked as external users.
* **Groups** - teams and their members, including service accounts, with each member's team role (Manager or Member).
* **Roles** - the four workspace roles and the two team roles, and who holds each.
* **Resources** - repositories, with a link to each one, and every way a principal reaches them:
  * explicit Admin, Write or Read privileges for a user, a team or a service account
  * Owners, who always have full administrative access to every repository
  * the repository's default privilege for Members and Managers
  * anonymous read access to public repositories
  * entitlement (download) tokens
* **Non-human identities** - service accounts (with the person who created them, their role and their teams) and repository entitlement tokens (with their creator and active state).
* **Credentials** - service account API keys, entitlement tokens, OpenID Connect (OIDC) provider trusts that let external CI tokens act as service accounts, and the connecting user's own API key. Oleria never requests or stores key or token values.
* **Activity** - the workspace audit log (on plans with audit log API access): logins, membership and role changes, team changes, service account and key events, entitlement token changes, SAML and two-factor policy changes, and repository events.

## Prerequisites

* A Cloudsmith workspace, and either an **Owner** account or permission to create a service account with the **Manager** role.
* Admin access on the Oleria platform to add a new integration.
* Activity from the audit log requires a Cloudsmith plan with audit log API access (Ultra or Enterprise). On other plans, Oleria syncs everything else and shows no activity. History depends on your plan's audit log retention.

## Choose an authentication method

| Method | When to use |
| :- | :- |
| **API key** (recommended) | A service account API key, or a user's API key. Use a dedicated service account so the connection survives people leaving, and so you don't have to refresh (and so disable) a person's existing key. |
| **Username and password** | HTTP Basic sign-in with a Cloudsmith username or email and password. Not available to accounts that sign in with SAML or a second factor. |

Cloudsmith API keys carry no scopes: Oleria sees what the key's owner can see. For complete coverage, use a service account with the **Manager** role that has **Admin** on every repository, or an Owner's key. With less, Oleria still syncs what the identity can read and reports the rest as a coverage gap.

Cloudsmith OIDC token exchange is designed for CI jobs that present a short-lived token from a trusted provider, so it can't be used as a stored Oleria connection.

## Create the credential in Cloudsmith

<Tabs>
  <Tab title="Service account API key">
    <Steps>
      <Step title="Create a service account">
        In Cloudsmith, go to **Services** on your workspace's accounts page, and create a service account (for example, `oleria`) with the **Manager** role.
      </Step>

      <Step title="Grant repository access">
        In each repository's settings, give the service account the **Admin** privilege. Oleria needs it to read the repository's privileges and entitlement tokens, and to run repository and token actions.
      </Step>

      <Step title="Copy the API key">
        Copy the service account's API key. Cloudsmith shows it only once, when you create the service account.
      </Step>
    </Steps>
  </Tab>

  <Tab title="User API key">
    <Steps>
      <Step title="Copy your API key">
        Signed in as an Owner, select your user icon in the top-right corner, then select **Personal API Keys**. Cloudsmith shows the key only after you select **Refresh**, and refreshing permanently disables your current key. Update any CLI or CI configuration that uses it.
      </Step>
    </Steps>
  </Tab>
</Tabs>

You also need your **workspace slug**: the short name in your Cloudsmith URLs, for example `my-company` in `https://app.cloudsmith.com/my-company`.

## Connect Cloudsmith to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations**, then select the **Cloudsmith** tile.
  </Step>

  <Step title="Complete the connection form">
    | Field | Notes |
    | :- | :- |
    | Authentication method | **API key (recommended)** or **Username and password**. |
    | Workspace slug | Required. Your Cloudsmith workspace slug. You can't change it after you connect. |
    | API key | Required for the API key method. |
    | Username or email | Required for the username and password method. |
    | Password | Required for the username and password method. |
    | API base URL (optional) | Leave empty to use `https://api.cloudsmith.io`. Only `https://*.cloudsmith.io` addresses are accepted. |
    | I authorize Oleria to perform write actions in Cloudsmith | Optional. Stored with the connection. [Remediation actions](#remediation-actions) currently run with the connected identity's role whether or not this is selected. |
  </Step>

  <Step title="Save the integration">
    Select **Authenticate**. Oleria checks that Cloudsmith authenticates the credential and that it can read the workspace and its members, then pins the connection to that workspace. When you edit the integration, leave **API key** or **Password** blank to keep the stored value.
  </Step>
</Steps>

## Verify the integration

Confirm the new instance appears on the **Connected** tab of your **Integrations** page with a status of **Healthy**.

## Remediation actions

| Action | What it does | Revert | Cloudsmith permission |
| :- | :- | :- | :- |
| Remove user | Removes a member from the workspace. Service accounts are refused. | No - re-adding needs a new invitation | Manager or Owner (Owner to remove an Owner) |
| Add user to role / Remove user from role | Changes a member's or service account's workspace role. Removing Owner or Manager sets the baseline **Member** role. Member can't be removed, only replaced. Removing **Collaborator** is refused because it would grant Member access; use **Remove access for external accounts** instead. Service accounts can hold only Manager or Member. | Yes, restores the previous role | Manager or Owner (Owner for Owner changes) |
| Add user to group / Remove user from group | Adds or removes a member or service account in a team. | Yes, with the previous team role | Manager or Owner |
| Revoke access to resource | Removes a member's or service account's explicit privilege on a repository. Access through a team, the Owner role, the repository's default privilege, or public visibility isn't changed, and the action still completes: if the member has no explicit privilege, nothing changes, and if they also reach the repository another way, they keep that access. Remove them from the team, change the default privilege, or use **Revoke anonymous access**. | Yes | Admin on the repository, or Owner |
| Create group | Creates a team. | Yes, deletes the team it created | Manager or Owner |
| Create user | Invites the email address to the workspace with the **Member** role. The person joins when they accept. | Yes, cancels the invitation while it's still pending. Once they accept, the revert doesn't remove them; use **Remove user**. | Manager or Owner |
| Revoke anonymous access | Makes a public repository private. | Yes, restores the previous repository type | Admin on the repository, or Owner |
| Remove access for external accounts | For a **Collaborator**, removes their explicit privileges on every repository and their team memberships. | Yes | Manager or Owner, and Admin on the repositories |
| Revoke external access to a resource | Removes every **Collaborator**'s explicit privilege on one repository. A Collaborator who reaches the repository through a team keeps that access; use **Remove access for external accounts** or remove them from the team. | Yes | Admin on the repository, or Owner |
| Revoke user sessions | Rotates the member's API key, so the old key stops working. A member has one API key for their whole Cloudsmith account, so the old key also stops working in their other workspaces; they must update it wherever they use it. Cloudsmith has no API to end web sessions. Service accounts are refused. | No | Manager or Owner (Owner for an Owner's key) |
| Disable NHI | Disables an entitlement token. | Yes, re-enables it | Admin on the repository, or Owner |

Oleria never acts on the identity the connection uses: it won't remove it from the workspace or a team, change its role, revoke its repository access, or rotate its key. It also never removes or demotes the last Owner of the workspace, and running **Remove user from group** never removes the last Manager of a team.

## Known limitations

* Cloudsmith has no API to suspend a member, so the leaver action removes the member.
* Member email addresses are redacted for identities below **Manager** unless the workspace grants the "see unredacted emails" privilege; use a Manager or Owner identity.
* Service accounts have no disabled state in Cloudsmith. Disable NHI covers entitlement tokens only.
* Cloudsmith's API doesn't expose last password change, the workspace-wide two-factor enforcement setting, last-used times for service accounts and tokens, or other users' personal API keys.
* Cloudsmith's audit log doesn't record repository privilege changes.
* Activity needs audit log API access, which Cloudsmith offers on Ultra and Enterprise plans. On other plans, Oleria shows no activity.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.