> ## 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. # Gravitee API Management > Connect Gravitee API Management (APIM) to Oleria to discover its users, service accounts, groups, scoped roles, non-human identities and their owners, and audit-trail activity. Connect Gravitee API Management (APIM) to Oleria to see who can manage your APIs and applications: console users and service accounts, environment groups, organization, environment, API, application, and group roles (held directly or through a group), and the personal access tokens, consumer applications, API keys, and client certificates that act as non-human identities (NHIs), with their owners. Oleria connects as a Gravitee user with the Organization **ADMIN** role, and can also change role and group membership, create users and groups, delete users, and disable NHIs. > [!NOTE] > > This integration supports Gravitee APIM 4.x, self-hosted or on Gravitee Cloud. Gravitee Access Management (AM) isn't covered. Each integration connects one APIM organization. If you have more than one, add an integration for each. See [Multi-instance support](https://docs.oleria.com/integrations/overview.md#multi-instance-support). ## What Oleria discovers Once connected, Oleria continuously discovers and maps the following from your APIM organization: * **Accounts** - every console user and service account in the organization, with name, email, creation date, and last sign-in. Oleria also shows: * **Status** - a user is enabled when Gravitee reports them as `ACTIVE`. Pending, rejected, and archived (deleted) users can't sign in. * **Account role** - the user's organization roles. Users with the Organization **ADMIN** role are marked as administrators. * **Single sign-on (SSO)** - users who sign in through an identity provider configured in Gravitee show SSO as required, with the provider type. Local users show SSO as not configured. * **MFA** - APIM has no MFA of its own. Local users show MFA as not required, and users from an identity provider as unavailable. * **Last activity** - the user's last console sign-in, or the newest use of one of their personal access tokens, whichever is later. * **Groups** - every group in each connected environment, with its members and each member's roles. Members who hold the group's **ADMIN** role are shown as the group's owners. * **Roles** - every organization and environment role, and a role for each API, application, and group role that someone holds, such as **OWNER — Payments API (API)**. Each role lists its Gravitee permissions. Roles that a user gets through a group show the group as their source. * **Memberships** - which users belong to which groups, and who holds each role, directly or through a group. * **Non-human identities (NHIs):** | NHI | What Oleria shows | | :- | :- | | Service account | A machine account with its roles, like any other user. Gravitee doesn't record who created a service account, so it has no owner. | | Personal access token | A token owned by its user, with creation date, expiry, and last use. A personal access token acts with all of its user's roles. | | Application (API consumer) | A machine account, active or archived, owned by its primary owner. If a group is the primary owner, the group's admins are the owners. Members with the application's **OWNER** role are shown as managers. OAuth and OIDC applications show their client secret as a credential, identified by client ID. An application whose subscriptions are all paused, for example by **Disable NHI accounts**, shows as disabled, with its credentials. | | API key | A token that authenticates its application, owned by the application's primary owner, and limited to the APIs and plans it's subscribed to. It shows its creation date, expiry, and status: active, paused, expired, or revoked. If Oleria can't read a key's subscriptions, its scope shows as unavailable. | | Client certificate | A certificate credential of its application, with fingerprint, subject, issuer, validity dates, and status. | Oleria never reads token, API key, client secret, or private key values. * **Activity** - the organization and environment audit trail: sign-ins, and user, membership, group, role, personal access token, application, API key, subscription, API, and identity provider events, attributed to the user who made them. Events by Oleria's own user are kept and tagged, because the audit trail can't tell Oleria's changes apart from other use of that user. The audit trail needs a Gravitee Enterprise Edition licence that includes it. See [Known limitations](#known-limitations). Oleria refreshes this data on its [regular sync schedule](https://docs.oleria.com/integrations/overview.md#sync-model). ## Prerequisites * Gravitee APIM 4.x, with its Management API reachable from the internet over HTTPS, by a host name that resolves to a public IP address. * For self-hosted APIM, the Management API host on Oleria's egress allowlist. Before you connect, contact [support@oleria.com](mailto:support@oleria.com) with the host name, such as `apim.example.com`, and ask for it to be allowlisted. Gravitee Cloud hosts (`*.api.gravitee.io`) are already allowlisted. * A Gravitee user with the Organization **ADMIN** role, to create Oleria's service account and its token. * Admin access on the Oleria platform to add a new integration. > [!WARNING] > > Organization **ADMIN** can change anything in the organization. Gravitee has no narrower role that can read the members of every API and application, so Oleria needs it to read your organization. Oleria uses the same credential for [remediation actions](#remediation-actions). Give Oleria its own service account, and store its token securely. ## Create the Oleria service account in Gravitee **1. Create a service account** In the Gravitee APIM Console, go to **Organization** > **Users** > **Add user**, and create a service account dedicated to Oleria, such as `oleria-governance`. **2. Grant Organization ADMIN** Open the service account (**Organization** > **Users** > *service account*) and set its organization role to **ADMIN**. **3. Generate a personal access token** Under **Organization** > **Users** > *service account* > **Tokens**, generate a personal access token and copy it. Gravitee shows it only once. You can use a local console user's username and password instead. Users who sign in through an identity provider have no Gravitee password, so they can't be used. **4. Collect the connection details** Copy your Management API URL, for example `https://apim.example.com/management`, or `https://..api.gravitee.io/management` on Gravitee Cloud. Note the organization ID if it isn't `DEFAULT`. To sync only some environments, note their IDs. ## Gravitee permissions Organization **ADMIN** holds every permission Oleria needs. The integration's **Capabilities and operation readiness** section lists them by row: | Row | Gravitee permissions | | :- | :- | | Read users | `ORGANIZATION_USERS[READ]`, `ORGANIZATION_USERS_TOKEN[READ]` | | Read groups | `ENVIRONMENT_GROUP[READ]`, `GROUP_MEMBER[READ]` | | Read roles | `ORGANIZATION_ROLE[READ]`, `ORGANIZATION_USERS[READ]`, `ENVIRONMENT_API[READ]`, `API_MEMBER[READ]`, `ENVIRONMENT_APPLICATION[READ]`, `APPLICATION_MEMBER[READ]` | Oleria also reads applications, their subscriptions, API keys, and client certificates (`APPLICATION_SUBSCRIPTION[READ]`, `APPLICATION_DEFINITION[READ]`), the audit trail (`ORGANIZATION_AUDIT[READ]`, `ENVIRONMENT_AUDIT[READ]`), and the console's sign-in settings and identity providers (`ORGANIZATION_SETTINGS[READ]`, `ORGANIZATION_IDENTITY_PROVIDER[READ]`). Remediation actions are optional. Each action lists these permissions, also held by Organization **ADMIN**: | Action | Gravitee permissions | | :- | :- | | Add user to role | `ORGANIZATION_USERS[READ]`, `ORGANIZATION_ROLE[UPDATE]`, `ORGANIZATION_USERS[UPDATE]`, `API_MEMBER[CREATE]`, `APPLICATION_MEMBER[CREATE]`, `GROUP_MEMBER[UPDATE]` | | Remove user from role | `ORGANIZATION_USERS[READ]`, `ORGANIZATION_ROLE[DELETE]`, `ORGANIZATION_USERS[UPDATE]`, `API_MEMBER[DELETE]`, `APPLICATION_MEMBER[DELETE]`, `GROUP_MEMBER[UPDATE]` | | Add user to group | `ORGANIZATION_USERS[READ]`, `ENVIRONMENT_GROUP[UPDATE]`, `GROUP_MEMBER[CREATE]` | | Remove user from group | `ORGANIZATION_USERS[READ]`, `ENVIRONMENT_GROUP[DELETE]`, `GROUP_MEMBER[DELETE]` | | Create user | `ORGANIZATION_USERS[READ]`, `ORGANIZATION_USERS[CREATE]`, `ORGANIZATION_USERS[DELETE]`, `ENVIRONMENT_GROUP[READ]`, `GROUP_MEMBER[CREATE]` | | Create group | `ENVIRONMENT_GROUP[READ]`, `ENVIRONMENT_GROUP[CREATE]`, `ENVIRONMENT_GROUP[DELETE]`, `GROUP_MEMBER[READ]` | | Delete user | `ORGANIZATION_USERS[READ]`, `ORGANIZATION_USERS[DELETE]` | | Disable NHI accounts | `API_SUBSCRIPTION[UPDATE]`, `APPLICATION_SUBSCRIPTION[READ]`, `APPLICATION_SUBSCRIPTION[DELETE]`, `APPLICATION_DEFINITION[READ]`, `ORGANIZATION_USERS_TOKEN[READ]`, `ORGANIZATION_USERS_TOKEN[DELETE]` | Gravitee doesn't report these permissions for a user, so before every action Oleria checks only that its user still holds Organization **ADMIN**. If it doesn't, the action fails and names the permissions it needs. ## Connect Gravitee to Oleria **1. Open the integration** Go to your Oleria workspace, select **Integrations** -> select **Gravitee API Management**. **2. Complete the connection form** Provide the following: | Field | Notes | | :- | :- | | Management API URL | Required. The `https` address of the Management API, such as `https://apim.example.com/management`, with no credentials, query, or fragment. It can't be changed after you create the integration. | | Organization ID (optional) | The APIM organization to connect. Leave blank for `DEFAULT`. It can't be changed after you create the integration. | | Environment IDs (optional) | A comma-separated list of environment IDs to sync. Leave blank to sync every environment the user can see. | | Authentication method | **Personal access token (recommended)** or **Username and password**. | | Personal access token | Required for **Personal access token (recommended)**. The service account's token. | | Username, Password | Required for **Username and password**. A local console user with Organization **ADMIN**. | **3. Confirm the connection** Select **Authenticate**. Before it saves anything, Oleria checks that the credential's user holds the Organization **ADMIN** role, and that the user can see every environment you listed. Find the newly connected organization on the **Connected** tab of your Oleria **Integrations** page. It's named **Gravitee APIM** followed by the Management API host. If **Authenticate** fails, the message says what's wrong: * **Gravitee getCurrentUser: HTTP 401** - check the personal access token, or the username and password. * **the Gravitee user must hold the Organization ADMIN role in organization** *ID* - give the user the Organization **ADMIN** role, or check **Organization ID (optional)**. * **Gravitee getCurrentUser: HTTP 404** - check that **Management API URL** ends with `/management` and that the organization ID exists. * **configured environments are not visible to the connection** - check **Environment IDs (optional)**. Each ID must exist and be visible to the user. ### Edit the integration When you edit the integration, you can change **Environment IDs (optional)**, **Authentication method**, and the credential. **Management API URL** and **Organization ID (optional)** can't be changed. To connect a different installation or organization, add a new integration. * Leave **Personal access token** or **Password** blank to keep the stored value. If you switch the authentication method, enter the new method's credential. * Clear **Environment IDs (optional)** to sync every environment again. Select **Update** to save. Oleria runs the same checks as **Authenticate**. ## Verify the integration Confirm the organization appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, review the discovered accounts, groups, roles, NHIs, and activity in your Oleria workspace. In the integration's **Capabilities and operation readiness** section, **Read users**, **Read groups**, and **Read roles** show **Available**. Oleria checks each row by reading a sample: users; the groups of the first connected environment; and the organization roles, users, and the members of one API and one application. If Gravitee refuses a read, the row shows **Needs permission**. Check that Oleria's user still holds Organization **ADMIN**. If Gravitee refuses or can't find a few items, such as one application's members, Oleria skips them, logs each one, and syncs the rest. If every item of a kind is refused, or more than 10% of them and at least 3, the sync of accounts, groups, roles, and NHIs fails, so incomplete data is never reported as complete. A refused list of groups, APIs, or applications always fails the sync. Client certificates are the exception: if Gravitee refuses them, applications still sync without them. ## Remediation actions Oleria can take these actions in Gravitee. Each needs Oleria's user to hold Organization **ADMIN**. See [Gravitee permissions](#gravitee-permissions). | Action | What it does | Revert | | :- | :- | :- | | Add user to role | Gives the user an organization, environment, API, application, or group role. For an API or application role, the user becomes a direct member with that role. For a group role, the user must already be a member of the group. | Supported - removes the role again. | | Remove user from role | Removes an organization, environment, API, application, or group role the user holds directly. | Supported - gives the role back. | | Add user to group | Adds the user to a group, with the group's default roles. | Supported - removes the user from the group. | | Remove user from group | Removes the user from a group. Oleria records the user's roles in the group first. | Supported - adds the user back with the recorded roles. | | Create user | Pre-registers a user with the first name, last name, and email address you provide, and can add them to groups. Gravitee emails the user a registration link, where they set their password. | Supported - deletes the user, if they still have the email address the action created them with. | | Create group | Creates a group with the name you provide, in the first connected environment. | Supported - deletes the group, but only while it has its original name and no members. | | Delete user | Deletes (archives) the user. | Not supported. Gravitee can't restore a deleted user. | | Disable NHI accounts | Revokes, pauses, or deletes the NHI, depending on its type. See the table below. | Depends on the type. | **Disable NHI accounts** works as follows: | NHI | What it does | Revert | | :- | :- | :- | | API key | Revokes the key. If the application uses one shared API key for all its subscriptions, the key is revoked for all of them, and the action's result says so. | Supported - reactivates the key. Not supported for a shared key: Gravitee can't reactivate it, so renew the application's key instead. | | Application | Pauses every accepted subscription of the application, so it can't call those APIs until they're resumed. | Supported - resumes the subscriptions the action paused that are still paused. | | Personal access token | Deletes the token. | Not supported. A deleted personal access token can't be restored, so its user must create a new one. | | Service account | Not supported. Gravitee has no disabled state for a service account. Use **Delete user** instead. | - | > [!NOTE] > > The **Remediations** page offers **Revert** only for **Remove user from group** and **Disable NHI accounts**. The integration supports the other reverts in these tables, but the Remediations page doesn't offer them yet. Oleria can revert only an action that completed or partially completed, never one that failed. > [!WARNING] > > **Delete user** and disabling a personal access token can't be undone. Gravitee has no disabled state for users, so Oleria doesn't offer **Disable user accounts** or **Enable user accounts**: deleting is the only way to remove a user's access. Keep these limits in mind when you use these actions: * Oleria refuses to delete its own user, to remove its own Organization **ADMIN** role, and to delete its own user's personal access tokens. Gravitee doesn't say which token Oleria uses, so Oleria refuses all of them. * **Remove user from role** refuses to remove the last Organization **ADMIN**. * **Add user to role** and **Remove user from role** refuse the **PRIMARY\_OWNER** role, which needs an ownership transfer in Gravitee. Gravitee also refuses **Delete user** while the user is the primary owner of an API or application: transfer ownership first. * **Remove user from role** refuses a role the user holds only through a group, and names the group. Remove the user from that group instead. It also refuses a group role that is the user's only role in the group: use **Remove user from group** instead. * **Add user to role** refuses an API or application role when the user is already a direct member with another role, and a group role when the user already holds another one. Remove that role first. * Environment roles can be changed only in a connected environment. * **Create user** refuses an email address that a user who isn't deleted already has. Gravitee doesn't take a password when it creates a user, and has no inactive state, so password and activation settings in the request are ignored and the result says so. * **Create group** refuses a name that a group in that environment already has, ignoring upper and lower case. * If the user, role, group, or NHI is already in the state the action asks for, Oleria makes no change, and reverting the action makes no change either. * After it changes an organization or group role, or deletes a user, Oleria reads the result again. If Gravitee accepted the change but it doesn't show, for example because an identity provider's role mapping applied the role again, the action fails and says so. * Reverting an action changes only what the action changed. If the target no longer exists, the revert makes no change and says why. ## Known limitations * **Audit trail needs Enterprise Edition.** Activity comes from the audit trail, which needs a Gravitee Enterprise Edition licence with the `apim-audit-trail` feature. On Community Edition, Oleria collects no activity and the sync still completes. Activity has no failed sign-ins, sign-outs, or IP addresses. * **No password change date or MFA.** APIM doesn't report when a user changed their password, and has no MFA of its own. * **No disable or session revocation.** APIM has no disabled state for users and no session API, so users can't be disabled, re-enabled, or signed out. Deleting is the only way to remove a user. * **APIs and plans aren't resources.** APIs appear only as the scope of API roles. Plans, subscriptions, and keyless plans aren't shown as access to resources. Subscriptions appear on their application and its API keys. * **Other role scopes.** Integration, cluster, API product, and AI catalog roles aren't read. * **Client certificates can't be disabled.** **Disable NHI accounts** doesn't apply to client certificates. To stop an application's certificates from being used, disable the application, which pauses its subscriptions. To remove a certificate, revoke it in Gravitee. * **Network access.** Oleria connects only over public HTTPS. A self-hosted Management API must be allowlisted for each customer. See [Prerequisites](#prerequisites). ## 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.