> ## 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.

# YouTrack

> Connect YouTrack to Oleria to continuously discover users, groups, project teams, roles, projects, organizations, permanent tokens, application passwords, OAuth clients, and audit log activity.

YouTrack is JetBrains' issue tracker and helpdesk. It comes with its own identity service, Hub, which holds accounts, tokens, and the audit log. Connect YouTrack to Oleria to see every account and how it signs in, the groups, project teams, and roles that grant access to each project, and the permanent tokens and OAuth clients that can act on the instance. Oleria connects with a YouTrack permanent token.

This integration works with YouTrack Cloud and YouTrack Server, version 2026.1 or later.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your YouTrack instance:

* **Accounts** - every user, with their name, login, email address, sign-in methods (password, including LDAP, or single sign-on), two-factor authentication status and method (authenticator app or WebAuthn security key), last access, last password change, when they were created, and whether they're banned. System Admin holders are marked as administrators. On YouTrack 2026.2 or later, the license type comes from each user's YouTrack user type: reporters are free, standard users and agents are paid. Helpdesk reporters are shown as external users, and the guest account represents anonymous visitors.
* **Non-human identities** - every permanent token and application password, each paired with a credential that shows its owner, when it was created and last used, and, for permanent tokens, who created it and the services its scope covers. Oleria also lists the OAuth clients registered in Hub (Hub services), with when each one was created and who created each one you added, when the audit log still holds its creation event. Oleria never reads token values or client secrets.
* **Groups** - custom groups, project teams, and the built-in **Registered Users** and **All Users** groups, with their members and, from the audit log, when each custom group and team was created. Nested groups and groups added to a project team are linked to their parent.
* **Roles** - every YouTrack role, built-in and custom, and who holds it, directly or through a group. A role granted in one project or organization appears as a separate role for that project or organization, such as `Project Admin (DEMO)`, so a scoped grant isn't mistaken for a global one.
* **Resources** - projects and organizations, with each project's creation date from the audit log, the projects each organization contains, the permissions each role grants on them, and each project's owner (leader). A role with project permissions that's granted globally applies to every project, and a role granted in an organization applies to the organization and all its projects.
* **Activity** - the Hub audit log: bans and unbans, password changes, group and role grants, token and OAuth client changes, sign-in module changes, and other configuration changes. Each event reads as a sentence, such as "admin removed user group Contractors", and events on a project link to the project in YouTrack.

Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model).

> [!NOTE]
>
> Oleria doesn't import issues, articles, or issue-level visibility settings.

## Prerequisites

* YouTrack Cloud or YouTrack Server 2026.1 or later. Oleria refuses older versions when you connect, because the group, role, and role-grant APIs it reads were added in 2026.1.
* A YouTrack user with the **System Admin** role, or a custom role with the permissions below, granted in the global scope. A dedicated service account is recommended: the token acts as this user and stops working if the user is banned or removed.
* Admin access to the Oleria workspace.

> [!NOTE]
>
> YouTrack Server must be reachable from Oleria over HTTPS at a public address. Before you connect, contact [support@oleria.com](mailto:support@oleria.com) to have your server's address allowlisted.

Each Oleria integration covers one YouTrack instance. If you have several instances, add one integration for each.

## Required permissions

The **System Admin** role covers everything. If you use a custom role, grant it in the global scope: Oleria checks the token's global permissions before an action runs.

Read permissions, for discovery:

| Permission | Key | What it adds |
| :- | :- | :- |
| **Read User Details** | `jetbrains.jetpass.user-read` | Accounts, permanent tokens, and application passwords. |
| **Low-level Admin Read** | `jetbrains.jetpass.low-level-read` | Groups, roles, and global role grants; the audit log, which supplies activity and last password change dates; the instance's sign-in modules. |
| **Read Service** | `jetbrains.jetpass.service-read` | OAuth clients (Hub services). |
| **Read Project Full** | `jetbrains.jetpass.project-read` | Projects and project teams. |
| **Update Project** | `jetbrains.jetpass.project-update` | Role grants made in a single project. |

Oleria needs all of them for a complete sync. YouTrack hides what a token can't see instead of returning a permission error, so when you select **Authenticate**, Oleria reads the token's effective permissions and refuses the token if any of these are missing, naming them.

Write permissions, only if you want Oleria to take [remediation actions](#remediation-actions):

| Permission | Key | What it allows |
| :- | :- | :- |
| **Update User** | `jetbrains.jetpass.user-update` | Banning and unbanning users, and revoking permanent tokens and application passwords. |
| **Low-level Admin Write** | `jetbrains.jetpass.low-level` | Adding users to and removing them from groups and project teams, and adding and removing role grants, together with **Update Project**. |
| **Create User** | `jetbrains.jetpass.user-create` | Creating users. |
| **Delete User** | `jetbrains.jetpass.user-delete` | Deleting users, and undoing Create user. |
| **Create Group** | `jetbrains.jetpass.group-create` | Creating groups. |
| **Delete Group** | `jetbrains.jetpass.group-delete` | Undoing Create group. |

## Create a permanent token

**1. Sign in as the connection user**

Sign in to YouTrack as the user that holds the **System Admin** role or your custom role.

**2. Create the token**

Open your profile, go to **Account Security** -> **Tokens**, and create a new permanent token. Its scope must include both **YouTrack** and **YouTrack Administration**. Oleria reads accounts, tokens, and the audit log through YouTrack Administration, and refuses a token without it.

**3. Copy the token**

Copy the token.

## Connect YouTrack to Oleria

**1. Open the integration**

Go to your Oleria workspace, select **Integrations**, then select the **YouTrack** tile.

**2. Complete the connection form**

| Field | Notes |
| :- | :- |
| YouTrack URL | The HTTPS address of your instance. For YouTrack Cloud, `https://example.youtrack.cloud`. An older `https://example.myjetbrains.com/youtrack` address is accepted and changed to `https://example.youtrack.cloud`. For YouTrack Server, your server address, including any path prefix. You can't change it after the integration is created. |
| Permanent token | The token you created. Editing the integration always asks for the token, so enter the current one if you don't replace it. |

**3. Authenticate**

Select **Authenticate**. Oleria checks that the token can call both YouTrack and YouTrack Administration, that the instance runs 2026.1 or later, and that the token holds the five read permissions above, then saves the integration.

## Verify the integration

Confirm YouTrack appears on the **Connected** tab of your Oleria **Integrations** page. After the first sync completes, you can review the discovered accounts, groups, roles, projects, and tokens in your Oleria workspace.

> [!NOTE]
>
> If you revoke or replace the permanent token in YouTrack, update it in Oleria by editing the integration.

## Remediation actions

Beyond discovery, Oleria can act on YouTrack access to remediate risk. Remediation needs the write permissions described above. Oleria checks the token's permissions before an action runs and reports any that are missing.

| Action | What it does | Reversible? | YouTrack permissions |
| :- | :- | :- | :- |
| Disable user / Enable user | Bans or unbans the user. If the user is already in that state, nothing changes. | Yes - restores the previous state. | Update User (`jetbrains.jetpass.user-update`), Read User Details (`jetbrains.jetpass.user-read`) |
| Add user to group / Remove user from group | Adds or removes the user in a custom group or a project team. The **Registered Users** and **All Users** groups include every user automatically, so they're refused. If the user is already in that state, nothing changes. | Yes - applies the opposite change. | Low-level Admin Write (`jetbrains.jetpass.low-level`), Update Project (`jetbrains.jetpass.project-update`), Low-level Admin Read (`jetbrains.jetpass.low-level-read`), Read User Details (`jetbrains.jetpass.user-read`) |
| Disable NHI | Revokes a permanent token or an application password. OAuth clients (Hub services) aren't supported, because Hub can only delete them, which would break the integration that uses them. | No - a revoked token or application password can't be restored. Its owner must create a new one. | Update User (`jetbrains.jetpass.user-update`), Read User Details (`jetbrains.jetpass.user-read`) |
| Add user to role | Grants a role to the user globally, in one project, or in one organization. If the user already holds it there, nothing changes. | Yes - removes the grant it made. | Low-level Admin Write (`jetbrains.jetpass.low-level`), Update Project (`jetbrains.jetpass.project-update`), Low-level Admin Read (`jetbrains.jetpass.low-level-read`), Read User Details (`jetbrains.jetpass.user-read`) |
| Remove user from role | Removes the user's own grant of that role. Access the user gets through a group stays; change the group's membership or role instead. | Yes - grants the role again. | Same as Add user to role |
| Revoke permission to resource | Removes the roles the user holds directly in that project or organization. Global roles, and an organization's roles on its projects, still apply; remove those with **Remove user from role**. If the user's only access is global or from the organization, nothing changes. | Yes - grants the roles again. | Same as Add user to role |
| Revoke anonymous access to resource | Removes the roles the guest account holds in a project or organization, so anonymous visitors lose that access. Roles granted to **All Users** also reach every signed-in user, so they're left in place. Global roles of the guest account still apply; remove those with **Remove user from role**. | Yes - grants the roles again. | Same as Add user to role |
| Create user | Creates a user with a sign-in password, inactive (banned) unless the request activates it, and adds it to the requested groups. Oleria uses the password in the request, or generates one. It never shows or stores the password; a user with a generated password sets their own with **Forgot password**. | Yes - deletes the user. | Create User (`jetbrains.jetpass.user-create`), Update User, Delete User (`jetbrains.jetpass.user-delete`), Read User Details, Low-level Admin Write (`jetbrains.jetpass.low-level`), Update Project (`jetbrains.jetpass.project-update`), Low-level Admin Read (`jetbrains.jetpass.low-level-read`) |
| Delete user | Deletes the user. YouTrack hands what the user owned, such as projects they lead, to the user the connection authenticates as. | No - a deleted user can't be restored. | Delete User (`jetbrains.jetpass.user-delete`), Read User Details (`jetbrains.jetpass.user-read`) |
| Create group | Creates a group. If a group with that name exists, nothing changes. | Yes - deletes the group while it still has no members and no roles; YouTrack replaces it with **Registered Users** wherever it was referenced. | Create Group (`jetbrains.jetpass.group-create`), Delete Group (`jetbrains.jetpass.group-delete`), Low-level Admin Read (`jetbrains.jetpass.low-level-read`) |

Oleria never bans or deletes the user the connection authenticates as, never removes that user from a group, project team, or role, and never revokes any of that user's permanent tokens or application passwords, including the connection's own token. It never deletes the guest account.

## Known limitations

* **No sign-in events.** The Hub audit log doesn't record sign-ins, sign-outs, or failed sign-ins. Dormant account detection uses each account's last access time in Hub.
* **OAuth client secrets aren't available.** Hub doesn't return the client secret of an OAuth client (Hub service), so Oleria shows no credential for it. Hub has no way to disable an OAuth client, so Disable NHI doesn't cover them.
* **Some credentials aren't collected.** Oleria doesn't inventory OAuth refresh tokens, SSH keys, or OAuth consents.
* **Two-factor authentication shows Hub's own enrollment.** YouTrack asks for Hub two-factor only on password sign-ins. A user who signs in only through single sign-on shows **Required** if they enrolled in Hub two-factor, and **Not required** (or **Enrollment required**, when a group requires it) otherwise, whatever your identity provider enforces.
* **Group role grants aren't changed by actions.** Remove user from role and Revoke permission change only the roles a user holds directly. To remove access a user gets through a group, remove them from the group, or change the group's roles in YouTrack.
* **Only project events link to a project.** Audit events about settings, permissions, users, groups, and roles aren't linked to a project.
* **Missing read permissions don't show on the Capabilities tab.** YouTrack returns no permission errors for reads, so Oleria checks them when you select **Authenticate** and names any that are missing, as described in [Required permissions](#required-permissions).
* **Identity provider links cover Okta's default issuer only.** Oleria links YouTrack to an Okta SAML app that uses Okta's default issuer, `http://www.okta.com/<app key>`. Apps on a custom Okta domain or on other identity providers share one issuer across apps, so Oleria doesn't link them.
* **YouTrack 2026.1 or later only.** Older versions are refused when you connect.

## 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.