> For the complete documentation index, see [llms.txt](https://docs.euno.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.euno.ai/sources/identity-and-organization/okta-integration/least-privilege-okta-api-token.md).

# Least-privilege Okta API token

Euno authenticates to Okta with a classic API token (SSWS). Only an Okta **admin** can create that token. The token has no scopes of its own: it always matches the **current** privileges of the account that created it.

Use a **dedicated service account** for the token. If that account is deactivated, Okta rejects the token. If you change the account's admin role, the token's access changes to match.

Euno only **reads**:

* Users (`GET /api/v1/users` and `GET /api/v1/users/me`)
* Groups (`GET /api/v1/groups`)
* Direct group members (`GET /api/v1/groups/{id}/users`)

## Option 1: Read-only Administrator (simplest)

A dedicated service account with Okta's built-in **Read-only Administrator** role can create a token and list users, groups, and group members. It cannot change users or groups. It can still view more of the Admin Console than Euno uses.

1. Create a dedicated Okta user that will not be deactivated (for example, `euno-okta@yourcompany.com`).
2. In the Admin Console, go to **Security** → **Administrators** and assign **Read-only Administrator**.
3. Sign in as that user and [create the token](/sources/identity-and-organization/okta-integration.md#step-1-create-an-okta-api-token).

Super Administrator and Organization Administrator also work, but they grant more privilege than Euno needs.

## Option 2: Custom admin role (tightest)

If your Okta org supports [custom admin roles](https://help.okta.com/en-us/Content/Topics/security/custom-admin-role/about-role-permissions.htm), you can limit the service account to view-only directory access.

Create the dedicated service account first (same as Option 1, step 1). You must be signed in as a Super Administrator for the rest. Custom roles cannot be assigned without a resource set: create the role, then a resource set, then bind both to the service account.

### Stage 1: Create the custom role

1. In the Admin Console, go to **Security** → **Administrators**.
2. Open the **Roles** tab and click **Create new role**.
3. Name the role (for example, `Euno Okta read`).
4. Grant only these permissions:

* Under user permissions: **View users and their details**
* Under group permissions: **View groups** (this includes viewing users assigned to each group)

5. Click **Save role**.

### Stage 2: Create a resource set

A resource set is the scope the custom role can see. Euno observes every user and group the token can list, so include all users and all groups unless you intentionally want a subset.

1. Still on **Security** → **Administrators**, open the **Resources** tab.
2. Click **Create new resource set**.
3. Name it (for example, `Euno directory`).
4. Click **Add resource**. From **Find a resource type**, choose **Users**, then select **All users**. Click **Save selection**.
5. Click **Add another resource type**. Choose **Groups**, then select **All groups**. Click **Save selection**.
6. Click **Create**.

{% hint style="info" %}
Include **both** Users and Groups. A resource set with only groups does not grant **View users and their details**, and a resource set with only users does not grant **View groups**. Okta shows a warning if the set does not match the role's permissions.

To observe only some of the directory, choose specific groups instead of **All users** / **All groups**. Users who are not in that scope, and groups that are not in that scope, will not appear in Euno.
{% endhint %}

### Stage 3: Assign the role and resource set to the service account

1. On the **Resources** tab, find the resource set you just created.
2. Click **Edit** → **View or edit assignments**.
3. In **Complete the assignment**:

* Choose the dedicated service account as the admin (you can pick a user or a group).
* Choose the custom role from Stage 1.

4. Click **Save changes**.

The service account now has view-only access to the users and groups in that resource set. It still cannot mint an API token; continue with the next stage.

### Stage 4: Create the token, then drop extra privilege

A custom role with only the view permissions above often **cannot create** an API token. Okta requires **Manage users** (or a built-in admin role) to mint the token. After the token exists, you can reduce the account to the view-only role; the token then inherits the reduced access.

1. Temporarily assign **Super Administrator**, **Organization Administrator**, or **Manage users** to the service account.
2. Sign in as the service account and [create the token](/sources/identity-and-organization/okta-integration.md#step-1-create-an-okta-api-token).
3. Sign out. As a Super Administrator, remove the temporary role and leave only the custom view-only role.

For Okta's own steps, see [Create an API token for a restricted administrator role](https://support.okta.com/help/s/article/create-an-okta-api-token-for-a-restricted-administrator-role).

## After you create the token

Return to [Configure the Okta source in Euno](/sources/identity-and-organization/okta-integration.md#step-2-configure-the-okta-source-in-euno) and paste the token into **API Token**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.euno.ai/sources/identity-and-organization/okta-integration/least-privilege-okta-api-token.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.