> ## 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. # Gremlin > Connect your Gremlin company to Oleria to discover who can run experiments where: users, teams, company and team roles, agents, API keys, team agent credentials, stored integration secrets, and security report activity. Gremlin is a reliability and chaos engineering platform. Its users can inject faults into your hosts, containers, and Kubernetes clusters, so it matters who can reach which team. Connect your Gremlin company to Oleria to see every active, invited, and revoked user, the company and team roles they hold, the teams they can reach, and the agents, API keys, and stored secrets that can act in your company. Oleria connects with a Gremlin API key and can take remediation actions directly from Oleria. Oleria reads access to the company and its teams. It doesn't list individual services, scenarios, experiments, or schedules. They belong to a team, so access to them appears through the team. One Oleria integration covers one Gremlin company. To connect another company, add another integration. ## What Oleria discovers Once connected, Oleria continuously discovers and maps the following from your Gremlin company: * **Accounts** - every company user, from the active, invited, and revoked user lists. Invited and revoked users are shown as disabled. Each account shows the user's name (or email if no name is set), email, company roles, and last activity: the later of the user's last sign-in and the last use of any of their API keys. * **Administrators** - users whose company roles let them manage users, security settings, roles, or Company Owners are marked as administrators. * **MFA** - a user who turned on time-based one-time password (TOTP) MFA is shown with MFA required. When your company requires MFA, users without it are shown as needing to enroll. If Oleria can't read a user's MFA status, it shows as unavailable. * **SSO** - required when your company enforces SAML sign-in, and configured when SAML is turned on. * **Authentication methods** - the sign-in methods your company allows, such as password, Google, OpenID Connect, and SAML, plus TOTP for users with MFA on and API key for users who own an active API key. * **Groups** - every team appears as a group, with its members and each member's team roles. Every member also holds the team's initial team role. When your company requires SAML or OpenID Connect claims, teams are shown as synced groups, because your identity provider sets team memberships at each sign-in. * **Roles** - the company roles, both built-in (such as **Company Owner**, **Company Security Administrator**, **Company Manager**, **Company Coordinator**, and **Company User**) and custom, with who holds each and the privileges each grants. Every user holds your company's default company role. The team roles, such as **Team Manager**, **Team User**, and **Team Viewer**, also appear in the role catalog. * **Resources** - every team, marked as production or not, and who can reach it: * the team's members, with the privileges of their team roles * the **Company Owner** role, which reaches every team * the team's agents * **Non-human identities (NHIs)**: * **Agents** - infrastructure agents, Failure Flags agents, and Private Network Integration agents, shown as workload identities with their team, whether they authenticate with the team secret or certificate, when they were last seen, and whether they're active. * **User API keys** - shown as personal access tokens, each paired with a credential that shows its status, creation date, expiry, and last use. Each key is linked to the user who created it, as its owner and as the account it acts as, because a Gremlin API key carries its owner's privileges. * **Team agent credentials** - each team's agent secret, with when and by whom it was last reset, and the team's current and previous agent certificates, with their fingerprint and expiry. Each is linked to the team's agents that authenticate with it. * **Company sign-in credentials** - the client secret of your custom OpenID Connect provider, and your SAML identity provider's primary and secondary signing certificates. * **Stored secrets** - the credentials Gremlin stores for Health Check integrations, team webhooks, and company notification integrations, with their status and creator where Gremlin reports them. Oleria reads metadata only. It never reads API key values, the team agent secret, certificate private keys, the OpenID Connect client secret, or stored secret values. * **Activity** - changes and sign-ins from your company's security reports, and SAML sign-in failures: * sign-ins, failed sign-ins, and sign-outs * API keys and team agent credentials created, rotated, and revoked * users invited, revoked, and reactivated, and company role changes * teams and custom roles created, changed, and deleted * requests Gremlin refused for lack of privilege * experiments (attacks) and scenario runs, from the experiment report * SAML sign-in failures, shown as failed sign-ins * any other change, kept as a custom event named after the request Gremlin's access report logs every API request. Oleria imports the changes and refusals, and skips successful reads such as page loads. Each event is linked to the user who made it, and events on a team link to that team. Gremlin doesn't record which API key made a request, so events made with a key are linked to the key's owner. Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model). ## Prerequisites * A dedicated Gremlin user for Oleria, with the company roles **Company Security Administrator** and **Company Manager**, and **Team Viewer** on every team. A user with **Company Owner** also works. See [Required permissions](#required-permissions). * Optionally, for remediation actions, an API key of a user who also holds the write privileges in [Remediation actions](#remediation-actions). * Your Gremlin company ID. * Admin access to the Oleria workspace. ## Required permissions Gremlin API keys have no scopes. A key carries the privileges of the user who created it, so the roles of the connection's user decide what Oleria can read. Use a dedicated user, so the connection doesn't depend on a person, and give it only the roles below. | Capability | Gremlin privileges | | :- | :- | | Read users | `COMPANY_USERS_READ`, `COMPANIES_READ`, `SECURITY_REPORTS_READ` | | Read groups | `TEAMS_READ`, `USERS_READ` | | Read roles | `COMPANY_USERS_READ`, `USERS_READ` | | Read NHIs and credentials | `ALL_API_KEYS_READ`, `COMPANIES_READ`, `CLIENTS_READ`, `INTEGRATIONS_READ`, `WEBHOOKS_READ`, `COMPANY_INTEGRATIONS_READ` | | Read activity | `SECURITY_REPORTS_READ`, `COMPANY_SECURITY_READ` | | [Remediation actions](#remediation-actions) | Required for actions: `COMPANY_USERS_WRITE`, `USERS_BATCH_WRITE`, `API_KEYS_WRITE`, `ALL_API_KEYS_READ`, `COMPANIES_WRITE` to create teams, and `USERS_WRITE` and `CLIENTS_WRITE` on the teams you change. `PROMOTE_DEMOTE_OWNER` to grant or remove **Company Owner**. | `USERS_READ`, `USERS_WRITE`, `CLIENTS_READ`, `CLIENTS_WRITE`, `INTEGRATIONS_READ`, and `WEBHOOKS_READ` are team privileges: the user needs them on each team, through a team role. The recommended least-privilege setup is: * **Company Security Administrator** - for MFA status, activity, and SAML sign-in failures. Only **Company Owner** and **Company Security Administrator** hold `SECURITY_REPORTS_READ` and `COMPANY_SECURITY_READ`. * **Company Manager** - for user API keys. Only **Company Owner** and **Company Manager** hold `ALL_API_KEYS_READ`. * **Team Viewer** on every team - for team members, agents, and team integrations. **Team Viewer** doesn't include `WEBHOOKS_READ`, so team webhooks need **Team User** on the team. **Company Owner** covers all of these, but it can also change everything in your company. If the user lacks an optional privilege, Oleria syncs everything else and leaves out what it can't read. Without `SECURITY_REPORTS_READ`, MFA shows as unavailable and activity isn't imported. Teams the user can't read have no members in Oleria. For actions, enter a **Remediation API key** of a user who also holds the write privileges. Actions use the remediation key when you set one, and the API key otherwise. ## Create an API key in Gremlin **1. Sign in as the dedicated user** Sign in to the Gremlin web app as the user the connection will use. **2. Create the key** Go to **Account Settings** and select the **API Keys** tab ([app.gremlin.com/profile/apikeys](https://app.gremlin.com/profile/apikeys)). Click **New API Key**, give the key a unique name and an optional description, then save it. Copy the key. **3. Create the remediation key (optional)** To run remediation actions with a different user, sign in as that user and create a key the same way. **4. Copy your company ID** In Gremlin, at the bottom of the left sidebar, select the copy icon next to your company name (the building icon). This copies your company ID. > [!NOTE] > > If your company sets an API key expiry, Gremlin revokes keys when it passes. Update the key in Oleria before it expires. ## Connect Gremlin to Oleria **1. Open the integration** Go to your Oleria workspace, select **Integrations**, then select the **Gremlin** tile. **2. Complete the connection form** | Field | Notes | | :- | :- | | API key | Required. The API key of the user Oleria reads with. Up to 512 characters. | | Company ID | Required. Your Gremlin company ID, from the copy icon next to your company name at the bottom of Gremlin's left sidebar. Up to 64 letters, numbers, and hyphens, starting with a letter or number. You can't change it after you connect. | | Remediation API key (optional) | An API key of a user that also holds the write privileges of the remediation actions you use. Leave it empty to run actions with the API key. | **3. Authenticate** Select **Authenticate**. Oleria checks that the API key is valid and belongs to a user of the company you entered, that the user can read the company and its users, and that Gremlin returns each user's email. If you entered a remediation API key, Oleria checks that it's valid and belongs to the same company. Then Oleria saves the integration. ## Verify the integration Confirm Gremlin appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, you can review the discovered users, teams, roles, agents, and API keys in your Oleria workspace. On the integration's **Capabilities** tab, **Read users**, **Read groups**, and **Read roles** show the privileges in [Required permissions](#required-permissions) and check them against your API key. If a row shows a missing permission, give the connection's user a role that includes it. > [!NOTE] > > To replace a key, edit the integration, enter the new key, and select **Update**. Leave **API key** or **Remediation API key** blank to keep the stored key. To stop using a remediation key, select **Remove stored remediation API key**. You can't change the **Company ID** of an existing integration. ## Remediation actions Beyond discovery, Oleria can act on Gremlin access to remediate risk. Oleria checks the privileges of the key's user before an action runs and reports any that are missing. Team privileges are checked on the team the action changes. | Action | What it does | Revert | Gremlin privileges | | :- | :- | :- | :- | | Disable user accounts | Revokes the user from the company. Gremlin keeps a revoked user, who can be reactivated. For a pending invitation, Oleria revokes the invitation. If the user is already revoked, nothing changes. | Yes - reactivates the user. For a revoked invitation, invites the email again if the invitation is gone. | `COMPANY_USERS_READ`, `COMPANY_USERS_WRITE` | | Enable user accounts | Reactivates a revoked user. If the user is already active, nothing changes. A pending invitation is refused, because it becomes active when the user accepts it. | Yes - revokes the user again. | `COMPANY_USERS_READ`, `COMPANY_USERS_WRITE` | | Add user to role | Grants a company role. If the user already holds it, or it's your company's default company role, nothing changes. | Yes - restores the user's previous company roles. | `COMPANY_USERS_READ`, `COMPANY_USERS_WRITE`, and `PROMOTE_DEMOTE_OWNER` for **Company Owner** | | Remove user from role | Removes a company role. If the user doesn't hold it, nothing changes. | Yes - restores the user's previous company roles. | `COMPANY_USERS_READ`, `COMPANY_USERS_WRITE`, and `PROMOTE_DEMOTE_OWNER` for **Company Owner** | | Add user to group | Adds a user to a team. If the user is already a member, nothing changes. | Yes - removes the user from the team. | `USERS_READ` and `USERS_WRITE` on the team, `USERS_BATCH_WRITE` | | Remove user from group | Removes a user from a team. Oleria first records the user's team roles. If the user isn't a member, nothing changes. | Yes - adds the user back and restores the recorded team roles. If the roles can't be restored, the revert reports a failure after adding the user back. | `USERS_READ` and `USERS_WRITE` on the team, `USERS_BATCH_WRITE` | | Disable NHI accounts - agent | Deactivates an infrastructure agent or a Private Network Integration agent. If it's already deactivated, nothing changes. | Yes - reactivates the agent. Gremlin refuses this when your agent licence limit is reached. | `COMPANIES_READ`, and `INTEGRATIONS_READ` and `CLIENTS_WRITE` on the agent's team | | Disable NHI accounts - API key | Revokes a user API key. If it's already revoked, nothing changes. | Partly - reinstates the key and confirms it's active again. Gremlin reactivates a key only for the user who owns it, so reverting another user's key usually reports that the key wasn't restored. The revert is also skipped when the user running the action owns a key with the same name. | `ALL_API_KEYS_READ`, `COMPANY_USERS_WRITE`, `API_KEYS_WRITE` | | Create user | Invites an email address to your company. If the user is already active or has a pending invitation, nothing changes. A revoked user is refused. Use **Enable user accounts** instead. | Yes - revokes the invitation while it's still pending. Once the user has accepted it, the revert is refused. | `COMPANY_USERS_READ`, `COMPANY_USERS_WRITE` | | Create group | Creates a team. If a team with exactly that name exists, nothing changes. A name that differs only in upper or lower case from an existing team is refused. | Yes - deletes the team. The revert is refused if anyone other than the connection's user, or any agent, has joined the team since. | `TEAMS_READ`, `COMPANIES_READ`, `COMPANIES_WRITE`, and `USERS_READ`, `CLIENTS_READ` and `INTEGRATIONS_READ` on the new team | Reactivating a user fails when your Gremlin user licence limit is reached. If the user's state, company roles, or team membership changed since the action ran, Oleria doesn't revert it, so it doesn't overwrite the newer change. If an agent or API key is no longer in Gremlin, the action fails with "NHI not found". Oleria refuses to: * revoke a user the connection runs as (the owner of the API key or of the remediation API key), remove a company role from it, or remove it from a team * revoke an API key that belongs to a user the connection runs as, because the connection may authenticate with it * revoke your company's only **Company Owner**, or remove their **Company Owner** role, including when reverting an earlier action * remove your company's default company role, which every user holds * grant or remove a team role through **Add user to role** or **Remove user from role**, because team roles are held per team When your company requires SAML or OpenID Connect claims, your identity provider sets company roles and team memberships at each sign-in. A role or team change Oleria makes for such a user is replaced at the user's next sign-in, and the action result warns you about it. Make these changes in your identity provider instead. **Disable NHI accounts** isn't supported for: * **Failure Flags agents** - Gremlin has no way to deactivate them. * **Team agent secrets and certificates** - Gremlin can only reset or replace them, which breaks every agent of the team and can't be undone. * **The OpenID Connect client secret and stored secrets** - Gremlin can only delete them with their sign-in or integration configuration. * **SAML identity provider certificates** - they're part of your SSO configuration. ## Known limitations * **No password change date.** Gremlin doesn't expose when a user last changed their password. * **No SCIM.** Gremlin documents no SCIM provisioning API. Provisioning works through SAML or OpenID Connect claims, so teams appear as synced groups when your company requires claims. * **Team roles can't be changed from Oleria.** Oleria shows each member's team roles, but doesn't offer an action to change them. Change team roles in Gremlin. Oleria changes team roles only to restore them when it reverts **Remove user from group**. * **No delete or session actions.** Gremlin has no way to delete a user, so revoke them with **Disable user accounts**. Gremlin can only end the session of the user making the request, so Oleria can't end other users' sessions. * **Activity needs Company Owner or Company Security Administrator.** Gremlin returns the security reports only to these roles, and SAML sign-in failures need `COMPANY_SECURITY_READ`. Without them, Oleria syncs everything else without activity. * **Reads aren't imported.** Gremlin's access report records every request, including page loads. Oleria imports changes, sign-ins, and refused requests, but not successful reads. * **Activity history is limited to 30 days.** Gremlin doesn't document how long it keeps security report data, so Oleria imports at most the last 30 days. * **MFA is TOTP only.** Gremlin supports only TOTP for MFA, on password sign-ins. For SSO sign-ins, MFA is up to your identity provider. Oleria reads each user's MFA status only for active users, and only with `SECURITY_REPORTS_READ`. * **Service accounts look like people.** Gremlin has no flag for users created to run API commands, so they appear as human users. Their API keys appear as NHIs. * **No agent owners.** Gremlin doesn't record who installed an agent, so agents show no owner. * **No AI agents.** Gremlin has no catalog of AI agents. Gremlin agents are infrastructure daemons and appear as workload identities. Grants to Gremlin's hosted MCP server aren't listed, because Gremlin offers no API for them. * **Some access isn't visible.** Assets shared between teams aren't collected, because Gremlin offers no API to list them. Only **Company Owner** is shown as reaching every team. Custom company roles aren't shown as reaching teams. * **Previous team certificates.** Gremlin doesn't say whether a team's previous agent certificate still authenticates, so its status shows as unavailable until it expires. * **Gremlin cloud only.** Oleria connects to `https://api.gremlin.com`. Gremlin Private Edition isn't supported. * **One company per integration.** Add one integration for each Gremlin company. ## 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.