> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Tools

> Use Okta agent tools in Ravenna rules to search the System Log, diagnose access failures, reset passwords and MFA, and manage groups and app assignments.

Okta provides agent tools for identity troubleshooting and access management. Reference them in <Tooltip headline="Agent rules" tip="Natural language instructions defining agent behavior" cta="Learn about agent rules" href="/documentation/automate/agents/configure#rules">agent rules</Tooltip> using @ mentions so your agent can answer access questions and fix common problems without a handoff.

***

## Diagnose access problems

Most access tickets are a variant of "why can't I get in". The System Log holds the answer, and `@Search Okta System Logs` lets the agent read it and explain what happened in plain language.

<AccordionGroup>
  <Accordion title="Search Okta System Logs" defaultOpen>
    Searches Okta System Log events for one person, so the agent can explain what happened instead of guessing. Covers sign-ins and lockouts, MFA enrollments and challenges, group membership changes, app assignments, policy evaluations, and admin actions.

    **Tool name:** `@Search Okta System Logs`

    **Filters:**

    * `User email` (required) - returns events where this person was the actor or the target
    * `Since` and `Until` - the time range to search. Defaults to the last 24 hours
    * `Event type` - a single Okta event type, for example `user.session.start` or `policy.evaluate_sign_on`
    * `Keyword` - free-text search across event fields
    * `Limit` - how many events to return, up to 100

    **What the agent learns:** each event's timestamp, type, severity, actor, target, and outcome, including the failure reason when Okta gives one. That reason is usually the whole answer, so the agent can name the cause rather than describing the symptom.

    **Common use cases:**

    * Explain a failed sign-in or a locked account
    * Find the MFA prompt a user started but never completed
    * Show when someone lost a group membership, and what they lost access to with it
    * Confirm whether a just-granted app assignment took effect
    * Reconstruct the sequence of events around an incident

    **Example rule:**

    <Prompt description="Okta sign-in troubleshooting rule">
      When someone reports they cannot sign in or an app is denying them
      access, use @Search Okta System Logs for their email over the last
      24 hours before replying. Tell them what the log shows in plain
      language, for example a failed MFA challenge or a removed group
      membership. If the fix is a password or MFA reset, offer it. Only
      escalate if the log does not explain the failure.
    </Prompt>

    <Note>
      This tool needs the `okta.logs.read` scope on your Okta app. If the scope is missing, the tool fails when the agent first calls it rather than at setup, so grant it before you write rules that depend on it.
    </Note>
  </Accordion>
</AccordionGroup>

### Common event types

Useful values for the `Event type` filter when you want to narrow a search:

| Event type                              | What it tells you                                              |
| --------------------------------------- | -------------------------------------------------------------- |
| `user.session.start`                    | A sign-in attempt, successful or failed                        |
| `user.account.lock`                     | The account was locked after repeated failures                 |
| `user.mfa.factor.activate`              | Someone finished enrolling a second factor                     |
| `user.authentication.auth_via_mfa`      | An MFA challenge was passed or failed                          |
| `policy.evaluate_sign_on`               | A sign-on policy allowed or denied the attempt                 |
| `group.user_membership.add`             | Someone was added to a group                                   |
| `group.user_membership.remove`          | Someone lost a group membership, and the access attached to it |
| `application.user_membership.add`       | An app assignment was granted                                  |
| `app.generic.unauth_app_access_attempt` | Someone tried to open an app they are not assigned to          |

Leave the filter empty to see everything for a person in the time range, which is usually the right first move.

***

## Look up people and groups

<AccordionGroup>
  <Accordion title="Get Okta User">
    Looks up a user by email and returns their profile, including name and account status. Use it to confirm you have the right person, or to check whether an account is active, suspended, or deprovisioned.

    **Tool name:** `@Get Okta User`
  </Accordion>

  <Accordion title="List Okta User Groups">
    Returns every Okta group a user belongs to. Useful for explaining what access someone currently has, and for spotting the group they are missing.

    **Tool name:** `@List Okta User Groups`
  </Accordion>

  <Accordion title="Check Okta Group Membership">
    Checks whether a user is in a specific group. Have the agent call this before adding or removing someone, so it does not report a change it did not make.

    **Tool name:** `@Check Okta Group Membership`
  </Accordion>
</AccordionGroup>

***

## Fix credentials

<AccordionGroup>
  <Accordion title="Reset Okta Password">
    Sends a forgot-password email to the user. This does not touch MFA.

    **Tool name:** `@Reset Okta Password`
  </Accordion>

  <Accordion title="Reset Okta MFA">
    Clears every enrolled factor so the user can re-enroll on their next sign-in. Use it when someone lost a device or got a new phone. This does not change their password.

    **Tool name:** `@Reset Okta MFA`
  </Accordion>

  <Accordion title="Generate Okta Password Reset Link">
    Creates a one-time reset link and delivers it to the target user by private Slack DM, so the link never appears in a shared ticket.

    **Tool name:** `@Generate Okta Password Reset Link`
  </Accordion>
</AccordionGroup>

<Note>
  Anyone can reset their own password or MFA. Only workspace admins can reset someone else's. When a non-admin asks, the agent explains the limit and suggests the other person self-serve.
</Note>

***

## Manage access

<AccordionGroup>
  <Accordion title="Add User to Okta Group">
    Adds a user to a group by name.

    **Tool name:** `@Add User to Okta Group`
  </Accordion>

  <Accordion title="Remove User from Okta Group">
    Removes a user from a group by name.

    **Tool name:** `@Remove User from Okta Group`
  </Accordion>

  <Accordion title="Add User to Okta Application">
    Assigns a user to an application. If the application name is ambiguous, the tool returns the matching candidates so the agent can confirm which one you meant.

    **Tool name:** `@Add User to Okta Application`
  </Accordion>

  <Accordion title="Remove User from Okta Application">
    Removes a user's application assignment.

    **Tool name:** `@Remove User from Okta Application`
  </Accordion>

  <Accordion title="Create Okta Group">
    Creates a group, with an optional description.

    **Tool name:** `@Create Okta Group`
  </Accordion>

  <Accordion title="Delete Okta Group">
    Deletes a group. Every member loses the membership, so the agent confirms before running it.

    **Tool name:** `@Delete Okta Group`
  </Accordion>

  <Accordion title="Activate Okta User">
    Activates a deactivated account, for example when someone returns from leave.

    **Tool name:** `@Activate Okta User`
  </Accordion>

  <Accordion title="Deactivate Okta User">
    Deactivates an account, removing the person's access.

    **Tool name:** `@Deactivate Okta User`
  </Accordion>
</AccordionGroup>

<Callout icon="shield" color="#6B7280">
  Write and delete tools default to **Requires confirmation**, and you can raise any of them to **Requires approval** per rule. See [tool execution policies](/documentation/automate/agents/configure#tool-execution-policies).
</Callout>

***

## Setup

<Steps>
  <Step title="Connect Okta">
    Follow the [client secret](/integrations/okta/setup/client-secret) or [private key](/integrations/okta/setup/private-key) setup guide.
  </Step>

  <Step title="Grant the log scope">
    Add `okta.logs.read` to your Okta app's granted scopes. Without it, every other tool here still works and only log search fails.
  </Step>

  <Step title="Check the agent's tools">
    Open your agent's settings and confirm the Okta tools appear under **Tools**. A disconnected integration shows a warning instead.
  </Step>

  <Step title="Write a rule">
    Reference the tools with @ mentions in a <Tooltip headline="Agent rules" tip="Natural language instructions defining agent behavior" cta="Learn about agent rules" href="/documentation/automate/agents/configure#rules">rule</Tooltip>, then test it on a real access question.
  </Step>
</Steps>

***

## Best practices

* **Search the log before escalating.** A rule that reads the log first turns most "I can't get in" tickets into an answer instead of a handoff.
* **Start without an event type filter.** The unfiltered last 24 hours usually contains the cause. Narrow only when the result is noisy.
* **Check membership before changing it.** Pair `@Check Okta Group Membership` with the add and remove tools so the agent reports what actually changed.
* **Name the person, not "you".** An admin often asks on someone else's behalf, so rules should refer to the target user by name.
* **Gate the destructive tools.** Put `@Delete Okta Group` and `@Deactivate Okta User` behind **Requires approval** in any rule an agent can reach on its own.

<Callout icon="link" color="#6B7280">
  Learn more about [configuring agents](/documentation/automate/agents/configure) and [Okta workflow actions](/integrations/okta/workflows)
</Callout>