> ## 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. # Outline > Connect an Outline workspace to Oleria to discover users, workspace roles, groups, API keys, OAuth applications, webhooks, and audit activity, and take remediation actions directly from Oleria. Outline is a team knowledge base and wiki. Connect an Outline workspace to Oleria to see who has access to the workspace, what role each person holds, which groups they belong to, and which API keys, OAuth applications, and webhooks can reach your data. Oleria reads this data from the Outline API with an API key or an OAuth connection. You can then review over-provisioned access and take action directly from Oleria. One Oleria integration covers one Outline workspace. Both Outline cloud workspaces (`https://.getoutline.com`) and self-hosted Outline are supported. ## What Oleria discovers Once connected, Oleria continuously discovers and maps the following from your Outline workspace: * **Users** - everyone in the workspace, including invited and suspended users, with name, email, workspace role, last activity, creation date, and who invited them. Suspended users are shown as disabled. Invited users who haven't signed in yet are shown as enabled with no last activity. Admins are marked as administrators, and guests are shown as external users. Oleria shows how each user last signed in within the last 90 days (for example Google, Microsoft, Slack, OIDC, SAML, or an email sign-in link), when your plan includes the audit log, and whether the workspace requires single sign-on. * **Roles** - Outline's four workspace roles: **Admin**, **Editor**, **Viewer**, and **Guest**, and who holds each one. Every user holds exactly one role. * **Groups** - the workspace's groups and their members. Group managers are shown as the owners of the group. * **Non-human identities (NHIs)**: * **API keys** - shown as personal access tokens, linked to the user who created them, with their scopes, creation date, expiry, and last use. Expired keys are shown as disabled. With an admin's API key, Oleria sees every user's API keys. * **OAuth applications** - OAuth clients registered in the workspace, shown as applications, with their client secret for confidential clients. Oleria shows which scopes the integration's own user granted to each application. * **Webhooks** - webhook subscriptions, shown as applications, with the user who created them and whether a signing secret is set. Oleria never stores the secret itself. * **Activity** - events from the Outline audit log, such as: * sign-ins and sign-outs, with the IP address * user invitations, role changes, suspension, and reactivation * API key creation and deletion * group changes, and users and groups added to or removed from collections and documents * share links created, changed, and revoked * workspace and sign-in settings changes Events Oleria doesn't recognize are kept as custom events. Oleria doesn't sync collections, documents, or share links. ## Prerequisites * An Outline workspace. Activity requires a plan that includes the audit log. * A workspace **Admin** account in Outline. Oleria acts as a user: an API key acts as the user who created it, and an OAuth connection acts as the user who approved it. That user must be an admin. * Admin access on the Oleria platform to add a new integration. ### Permissions Outline API keys have optional scopes. Oleria needs these: | Use | Scope | | :- | :- | | Discovery | `read` | | Remediation actions | `read write`, or leave the scopes empty for full access | If you narrow the scopes instead of using `read`, each part of the sync needs its own read scope: users and roles need `users:read`, groups need `groups:read`, and the workspace details need `auth:read`. If the key can't read API keys, OAuth applications, webhooks, or activity, Oleria skips that part and syncs the rest. With OAuth, Oleria asks for `read write`, which covers discovery and remediation actions. > [!NOTE] > > Use a dedicated API key for this integration, created by an admin account that stays active. If that admin is suspended, demoted, or removed, the key stops working. ## Choose an authentication method * **API key** (recommended, and the default) - an Outline API key created by an admin. * **OAuth** - your own OAuth application in Outline, approved by an admin when you connect. Use it if your policy requires OAuth. ## Create an API key in Outline **1. Open API keys** Sign in to Outline as an admin, and go to **Settings** -> **API Keys**. **2. Create the key** Select **New API key**. Name it `Oleria`. In **Scopes**, enter `read` for discovery only, or `read write` if you want to run remediation actions. Choose an expiration that fits your policy. **3. Copy the key** Copy the key, which starts with `ol_api_`. Outline shows it only once. > [!NOTE] > > The Outline interface changes over time. If these steps don't match what you see, refer to Outline's [API documentation](https://www.getoutline.com/developers). ## Set up OAuth in Outline Skip this section if you use an API key. **1. Create an OAuth application** Sign in to Outline as an admin, go to **Settings** -> **Applications**, and create a new application. Name it `Oleria`. **2. Add the redirect URI** Set the redirect URI to your Oleria workspace URL (the one in your browser's address bar) followed by `/workspace/integrations/outline/connect`. For example: ``` https://acme.oleria.io/workspace/integrations/outline/connect ``` Oleria uses the same redirect URI when you add the integration and when you reconnect it. **3. Copy the client credentials** Copy the application's client ID and client secret. ## Connect Outline to Oleria **1. Open the integration** Sign in to your Oleria workspace, navigate to **Integrations**, and select **Outline**. **2. Complete the connection form** Fill in the connection form: | Field | Notes | | :- | :- | | Authentication method | **API key (recommended)**, the default, or **OAuth**. | | Workspace URL | Required. Your Outline workspace address, for example `https://your-team.getoutline.com`, or the address of your self-hosted Outline. | | API key | API key method only. The API key you created. | | Client ID | OAuth method only. From the OAuth application you created. | | Client secret | OAuth method only. From the OAuth application you created. | **3. Authenticate** Select **Authenticate**. With an API key, Oleria checks the key against your workspace before it saves the integration, and refuses a key that doesn't belong to an admin. With OAuth, you're redirected to Outline to approve read and write access, then back to Oleria. Approve as a workspace admin: Oleria refuses the connection if the approving user isn't an admin. The integration is named after your Outline workspace. > [!NOTE] > > For self-hosted Outline, Oleria must be able to reach your Outline address over HTTPS. Contact [support@oleria.com](mailto:support@oleria.com) to allow the address. ## Verify the integration Confirm the Outline integration appears on the **Connected** tab of your Oleria **Integrations** page. After the first sync completes, review the discovered users, roles, groups, NHIs, and activity in your Oleria workspace. ## Remediation actions Oleria runs actions as the user the integration connects as: the admin who created the API key, or the admin who approved the OAuth connection. Before an action runs, Oleria checks that this user is an admin and that the API key's scopes, or the OAuth grant, allow the action. | Action | What it does | Revert | | :- | :- | :- | | Disable user accounts | Suspends the user. Suspended users can't sign in, and their content stays. | Supported - reactivates the user, if they are still suspended. | | Enable user accounts | Reactivates a suspended user. | Supported - suspends the user again, if they are still active. | | Add user to role | Changes the user's workspace role. Because every user holds exactly one role, the new role replaces the old one. | Supported - restores the previous role, if the user still holds the role the action set. | | Add user to group | Adds the user to the group as a member. | Supported - removes the user from the group again. | | Remove user from group | Removes the user from the group. | Supported - adds the user back, as a group manager if they were one. | | Create user | Invites the email address to the workspace with the workspace's default role for new users, and can add the new user to groups. If a user with that email is already in the workspace, including a suspended or invited user, nothing changes. If adding the new user to a group fails, the invitation stays in Outline and the action can't be reverted. Delete the user in Outline or with **Delete user**. | Supported - deletes the user, if the action invited them. | | Delete user | Deletes the user. Outline removes the person's name from everything they wrote. To keep their content attributed, use **Disable user accounts** instead. | Not supported - Outline can't restore a deleted user. | | Create group | Creates a group with the name you give. If a group with that name already exists, nothing changes. | Supported - deletes the group, if the action created it and it still has no members. | Each action needs these permissions: | Action | Required permissions | | :- | :- | | Disable user accounts, Enable user accounts, Add user to role, Delete user | Admin workspace role, `users:write`, `apiKeys:read`, `auth:read` | | Add user to group, Remove user from group, Create group | Admin workspace role, `groups:write`, `apiKeys:read`, `auth:read` | | Create user | Admin workspace role, `users:read`, `users:write`, `groups:write`, `apiKeys:read`, `auth:read` | The `read write` scopes cover all of them, and an OAuth connection asks for them. Oleria refuses these actions and sends no change to Outline: * Suspending, deleting, or changing the role of the user the integration connects as. Keep these points in mind: * If the target is already in the requested state, the action succeeds without making a change, and there's nothing to revert. * Reverting checks the target first. If it changed after the action ran, Oleria leaves it as is. ## Known limitations * **The connection belongs to a person.** Outline has no service accounts. An API key acts as the admin who created it, and an OAuth connection acts as the admin who approved it. If that admin is suspended, demoted, or removed, the connection stops working. * **NHIs can't be disabled from Oleria.** Outline can only delete API keys, and only from the Outline interface, not through its API. OAuth applications and webhooks have no disabled state. Manage them in Outline under **Settings**. * **OAuth application owners aren't shown.** Outline doesn't record who registered an OAuth application. OAuth consents are shown only for the user the integration connects as. * **Activity depends on your plan.** The audit log needs a plan with the audit log feature and an admin connection. Outline keeps audit events for one year. The first sync imports recent activity only. * **No MFA status.** Outline has no multi-factor authentication of its own. Second factors are enforced by your sign-in provider, so MFA status isn't known. * **No user remove-from-role action.** Every Outline user holds exactly one role. To change it, use **Add user to role**. * **Not synced.** Collections, documents, share links, and their permissions aren't synced. ## 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.