# BambooHR
Source: https://docs.tryrisotto.com/dashboard/settings/people/connect/bamboohr

Connect BambooHR as your HRIS to power employee self-service

Connect BambooHR as your HRIS so Risotto can answer employee questions and take actions like checking PTO balances, submitting time off requests, and updating home addresses. These actions are all controlled by the [People Actions](/dashboard/settings/people/actions) settings.

In the dashboard, BambooHR appears as a row under **Settings > People > Connect** with the description "Allows Risotto to manage HR operations like employee data and time off" and a **Connect** button on the right.

## How the Integration Works

Risotto connects to BambooHR through BambooHR's OAuth 2.0 authorization flow. Each Risotto org installs against a single BambooHR tenant identified by your **company subdomain** (the `acme` in `acme.bamboohr.com`). After install, Risotto stores access and refresh tokens scoped to that tenant and uses them to call the BambooHR REST API on your behalf.

When an employee asks Risotto something that needs HRIS data (i.e. "What's my PTO balance?"), Risotto resolves their BambooHR employee record by matching their work email, then calls only the BambooHR endpoints required to answer that request.

## Install from BambooHR

You must be a BambooHR admin to approve the install.

<Steps>
  <Step title="Start the install from Risotto">
    In the dashboard, go to **Settings > People > Connect** and click **Connect** next to BambooHR. Enter your BambooHR company subdomain (`acme` portion of `acme.bamboohr.com`) and click **Continue**.
  </Step>

  <Step title="Approve the install in BambooHR">
    You'll be redirected to your BambooHR tenant (`acme.bamboohr.com`) to sign in
    and approve the requested OAuth scopes for the Risotto app. BambooHR redirects
    you back to the Risotto dashboard once the install is complete.
  </Step>

  <Step title="Confirm the connection">
    The BambooHR row in **People Connect** updates to show the integration is connected.
  </Step>
</Steps>

<Note>
  The subdomain accepts lowercase letters, numbers, and hyphens only. If you're
  unsure of your subdomain, check the URL you use to sign in to BambooHR.
</Note>

<Warning>
  A BambooHR tenant can only be connected to one Risotto org at a time. If the
  same subdomain is already connected to another Risotto org, the install fails
  with "Please disconnect BambooHR from your other Risotto org." Disconnect from
  the other org first, then retry the install.
</Warning>

## Requested OAuth Scopes

During install, Risotto requests the following BambooHR OAuth scopes:

| Scope | Purpose |
| - | - |
| `offline_access` | Issue refresh tokens so Risotto keeps access without re-prompting your admin |
| `openid`, `email` | Identify the BambooHR account that approved the install |
| `employee` | Read basic employee records |
| `employee:name` | Read first, last, display, and preferred name |
| `employee:contact` | Read work and home email |
| `employee:job` | Read job title, department, division, location, hire date, and supervisor |
| `employee:management` | Read manager / supervisor relationships |
| `sensitive_employee:address` | Read the employee's home address |
| `sensitive_employee:address.write` | Update the employee's home address |
| `time_off` | Read PTO policy types, balances, and existing time off requests |
| `time_off.write` | Submit time off requests on behalf of the requesting employee |

## Data Fields That Sync

Risotto reads only the fields it needs to fulfill an active request. Nothing is written back to BambooHR unless the matching People Action is enabled.

### Employee profile (read)

Pulled from `GET /api/v1/employees/{id}`:

| BambooHR field | Used for |
| - | - |
| `firstName`, `lastName` | Name resolution and personalization |
| `displayName` | Preferred display name in Risotto responses |
| `preferredName` | Fallback display name when `displayName` is empty |
| `workEmail` | Primary identifier matched against the requester's Slack email |
| `homeEmail` | Secondary identifier when `workEmail` is missing |
| `jobTitle` | Employee profile lookups |
| `department` | Employee profile lookups |
| `division` | Employee profile lookups |
| `location` | Work location lookups |
| `hireDate` | Start date lookups |
| `supervisor` | "Who's my manager?" style lookups |
| `supervisorEmail` | Routing requests that need manager approval |
| `employmentHistoryStatus` | Detecting whether the employee is currently active |

### Home address (read and write)

Pulled from `GET /api/v1/employees/{id}` when address access is needed, and written back via `POST /api/v1/employees/{id}` when **Update Home Address** is enabled:

| BambooHR field | Used for |
| - | - |
| `address1` | Street address line 1 |
| `address2` | Street address line 2 |
| `city` | City |
| `state` | State or province |
| `country` | Country |
| `zipcode` | Postal / ZIP code |

### Time off (read and write)

| BambooHR endpoint | Used for |
| - | - |
| `GET /api/v1/employees/{id}/time_off/calculator` | Current balance, units (hours or days), and policy type for each plan the employee is assigned to |
| `GET /api/v1/time_off/requests` (filtered by `employeeId`) | Recent and upcoming time off requests for the employee |
| `POST /api/v1/employees/{id}/time_off/request` | Submit a new time off request. Requests are created with status `requested` and routed for approval |

<Note>
  Discretionary and manual BambooHR policies don't track a running balance, so
  Risotto surfaces those as "no tracked balance" rather than a literal `0`.
</Note>

## Supported Actions

BambooHR supports the following [People Actions](/dashboard/settings/people/actions):

<CardGroup>
  <Card title="Get Employee Info" icon="id-card">
    Look up the requesting employee's profile, title, department, work location,
    manager, and start date. Turn it on in [Support agent >
    Context](/dashboard/settings/support-agent/context).
  </Card>

  <Card title="Get Home Address" icon="house">
    View the home address on file for the requesting employee.
  </Card>

  <Card title="Update Home Address" icon="house-chimney-user">
    Update the home address on file for the requesting employee.
  </Card>

  <Card title="Get PTO Balance" icon="calendar-check">
    Retrieve balances for each policy type the employee is assigned to.
  </Card>

  <Card title="Request PTO" icon="calendar-plus">
    Submit a time off request for the requesting employee. Requests are created
    with status `requested` and follow your BambooHR approval flow.
  </Card>
</CardGroup>

## Terminated Employees

Risotto checks the `employmentHistoryStatus` field on every BambooHR lookup. When the field indicates the employee is no longer active, [People Actions](/dashboard/settings/people/actions) stop running for that employee and requests are escalated, even if their Slack account is still active.

## Disconnecting

To disconnect Risotto from BambooHR, click **Connected** on the BambooHR row in **People Connect**, then click **Disconnect...** and confirm. Risotto revokes its stored access and refresh tokens. To fully remove the app from BambooHR, an admin should also revoke the Risotto authorization from **Account > API Keys & Installed Apps** inside BambooHR.


# HiBob
Source: https://docs.tryrisotto.com/dashboard/settings/people/connect/hibob

Connect HiBob as your HRIS to power employee self-service

Connect HiBob as your HRIS to power employee self-service. Once connected, Risotto can look up employee information, retrieve PTO balances, submit time off requests, and view home addresses on file — controlled by the [People Actions](/dashboard/settings/people/actions) settings.

## Install from the HiBob Marketplace

In the dashboard, HiBob appears as a row under **Settings → People → Connect** with the description "Allows Risotto to manage HR operations like addresses and time off requests" and an **Install** button on the right.

Risotto connects to HiBob through the HiBob Marketplace, it handles authentication and persists OAuth tokens automatically.

<Steps>
  <Step title="Start the install from Risotto">
    In the dashboard, go to **Settings → People → Connect** and click **Install** next to HiBob. You'll be redirected to the HiBob Marketplace.
  </Step>

  <Step title="Approve the install in HiBob">
    Sign in to HiBob as an admin if prompted, then approve the requested
    permissions for the Risotto app. HiBob redirects you back to the dashboard
    once the install is complete.
  </Step>

  <Step title="Confirm the connection">
    The HiBob row in **People Connect** updates to show the integration is connected. A toast confirms `HiBob connected successfully`.
  </Step>
</Steps>

<Note>
  Only HiBob admins can install marketplace apps. If the **Install** button
  redirects you to HiBob without an approval screen, ask an admin in your
  workspace to complete the install.
</Note>

<Warning>
  A HiBob tenant can only be connected to one Risotto org at a time. If the same
  HiBob tenant is already connected to another Risotto org the install fails
  with "Please disconnect HiBob from your other Risotto org," disconnect from
  the other org first, then retry the install.
</Warning>

## Requested Permissions

Risotto requests the following HiBob OAuth scopes during install:

| Scope | Purpose |
| - | - |
| `employee_data:read` | Look up employees and retrieve home addresses |
| `timeoff:read` | Read PTO policy types, balances, and existing time off entries |
| `timeoff:write` | Submit time off requests on behalf of the requesting employee |

## Supported Actions

HiBob supports the following [People Actions](/dashboard/settings/people/actions):

<CardGroup>
  <Card title="Get Employee Info" icon="id-card">
    Look up the requesting employee's profile, title, department, work location,
    and start date. Turn it on in [Support agent >
    Context](/dashboard/settings/support-agent/context).
  </Card>

  <Card title="Get Home Address" icon="house">
    View the home address on file for the requesting employee.
  </Card>

  <Card title="Get PTO Balance" icon="calendar-check">
    Retrieve balances for each policy type the employee is assigned to.
  </Card>

  <Card title="Request PTO" icon="calendar-plus">
    Submit a time off request for the requesting employee in days mode.
  </Card>
</CardGroup>

<Warning>
  **Update Home Address** is not supported for HiBob. The HiBob public API does
  not expose address writes. Employee addresses can only be edited in the HiBob
  UI by the employee or an HR admin.
</Warning>

## Terminated Employees

When HiBob marks an employee as having left the company, Risotto receives a webhook from HiBob and immediately stops [People Actions](/dashboard/settings/people/actions) from running for that employee. Requests from former employees are escalated, even if their Slack account is still active.

## Troubleshooting

HiBob does not always fail loudly. With valid credentials but missing grants, a people search comes back empty and a profile comes back with fields removed, while the connection still shows as connected. Risotto names the cause in the tool result and, for the sticky cases, sends one admin alert until the grant is fixed.

<Accordion title="Risotto finds no employee, or finds one with only an email">
  If the connection cannot see any employee at all, Risotto says so: "The HiBob connection is authenticated but cannot see any employees at all." In Bob, add the connection's service user to a permission group whose viewing scope covers employees.

  If HiBob returns the employee but the name and other profile fields are missing, Risotto reports that HiBob withheld them. In Bob, grant the connection's permission group view access on the People's data categories (**Basic info** and **Work**).
</Accordion>

<Accordion title="Time off requests fail with a permission error">
  HiBob accepted the credentials but refused the time off read (HTTP 403). In
  Bob, grant the connection's permission group view access on the **Time Off**
  category.
</Accordion>

<Accordion title="Risotto says HiBob rejected the connection's credentials">
  HiBob answered with HTTP 401. An org admin must reconnect HiBob under
  **Settings > People > Connect**.
</Accordion>

## Disconnecting

To disconnect Risotto from HiBob, click **Connected** on the HiBob row in **People Connect**, then click **Disconnect...** and confirm. You'll be redirected to the [HiBob Marketplace](https://app.hibob.com/marketplace/manage-apps) to remove the Risotto app from your workspace, which revokes the OAuth tokens.


# Rippling
Source: https://docs.tryrisotto.com/dashboard/settings/people/connect/rippling

Connect Rippling as your HRIS to power employee self-service

Connect Rippling as your HRIS so Risotto can answer employee HR questions directly in Slack instead of routing them to your People team. Once connected, an employee can ask for their PTO balance, submit a time off request, check their job details, or look up the home address on file.

In the dashboard, Rippling appears as a row under **Settings > People > Connect** with the description "Allows Risotto to manage HR operations like employee data and time off" and an **Install** button on the right.

## Why connect Rippling

<CardGroup>
  <Card title="Deflect repetitive HR tickets" icon="ticket">
    "How much PTO do I have left?" and "can I take next Friday off?" are among
    the most common requests People teams receive. Risotto answers them from
    live Rippling data.
  </Card>

  <Card title="Keep your roster current" icon="users">
    Risotto syncs your employee roster from Rippling, so it knows who works
    there without you maintaining a separate user list.
  </Card>

  <Card title="Stop serving former employees" icon="user-slash">
    When someone is terminated in Rippling, Risotto stops acting on their
    requests.
  </Card>

  <Card title="No new surface for employees" icon="slack">
    Employees stay in Slack. They don't need to remember where Rippling lives or
    how to navigate it.
  </Card>
</CardGroup>

## Prerequisites

Have these in place before you start:

* **A Rippling admin account.** Only Rippling admins can install App Shop apps.
* **A Risotto admin account.** Installing, syncing, and disconnecting all require permission to manage the org.
* **Account provisioning configured for Risotto in Rippling.** Rippling's provisioning rules determine which employees are in scope for Risotto. These rules populate the `PROVISIONING` group that Risotto's roster sync reads; without it, the sync has nothing to reconcile and reports a failure.
* **The Rippling company is not connected to another Risotto org.** One Rippling company maps to exactly one Risotto org.

## Install from the Rippling App Shop

Risotto connects to Rippling through the Rippling App Shop. The App Shop handles authentication and Risotto persists OAuth tokens automatically.

<Steps>
  <Step title="Start the install">
    Find the Risotto app in the [Rippling App Shop](https://app.rippling.com/apps) and click **Install**, or start from the Risotto dashboard at **Settings → People → Connect** and click **Install** next to Rippling.
  </Step>

  <Step title="Approve the install in Rippling">
    Sign in to Rippling as an admin if prompted, then approve the requested
    permissions for the Risotto app. Rippling redirects you back to the Risotto
    dashboard once approval is complete.
  </Step>

  <Step title="Confirm the connection">
    Back in the Risotto dashboard, sign in if prompted and you'll land on
    **Settings → People → Connect**, where the install finishes automatically. The
    Rippling row updates to show the integration is connected and begins its first
    employee sync.
  </Step>

  <Step title="Enable the actions you want">
    Installing the integration does not by itself let Risotto do anything. Go to **Settings → People → Actions** and enable each [People Action](/dashboard/settings/people/actions) you want available. To let the agent look up the employee record, turn on **Agent access** on the **People** tab of [Support agent > Context](/dashboard/settings/support-agent/context). Every action is off until you turn it on.
  </Step>
</Steps>

<Note>
  Only Rippling admins can install App Shop apps. If the **Install** button
  redirects you to Rippling without an approval screen, ask an admin in your
  workspace to complete the install.
</Note>

<Warning>
  A Rippling company can only be connected to one Risotto org at a time. If the
  same Rippling company is already connected to another Risotto org, the install
  fails with "Please disconnect Rippling from your other Risotto org."
  Disconnect from the other org first, then retry the install.
</Warning>

## Requested Permissions

During install, Risotto requests access to the following Rippling data through the App Shop integration:

| Access | Purpose |
| - | - |
| Employee profile | Look up name, work email, job title, department, work location, and start date |
| Home address | Read the home address on file for the requesting employee |
| Leave balances | Read PTO policy types and balances for each plan the employee is assigned to |
| Leave requests | Read existing time off requests and submit new ones on the employee's behalf |
| Groups | Read the provisioning group that defines which employees are in scope |

<Note>
  Rippling negotiates the exact permission scopes through the App Shop
  integration during approval. Risotto reads only the fields it needs to fulfill
  an active request.
</Note>

## Data Flows

The integration runs four distinct flows. Two keep your roster current in the background; two run only when an employee asks for something.

| Flow | Direction | Trigger |
| - | - | - |
| Employee roster sync | Rippling → Risotto | On install, daily, or on demand |
| Provisioning webhooks | Rippling → Risotto | Rippling sends the event (\~5 minute delay) |
| Employee data lookup | Rippling → Risotto | An employee asks; read live, nothing stored |
| Time off request | Risotto → Rippling | An employee asks and confirms |

### Employee roster sync

Risotto reads the `PROVISIONING` group from Rippling and reconciles its own roster against it. Employees in the group are added or updated; Rippling-sourced identities no longer in the group are marked inactive with an audit entry.

This flow runs at three moments:

* **Once on install**, so a new connection is populated immediately.
* **Once a day**, in an overnight sweep (around 08:20 UTC).
* **On demand**, when an admin clicks **Sync now**.

The sync is idempotent. Re-running it with no upstream change writes nothing. It's also locked per org, so overlapping triggers collapse into the single run already in flight rather than stacking up.

<Note>
  The sync deliberately skips deactivating employees when the picture from
  Rippling looks incomplete such as an empty provisioning group, or a roster too large
  to read in one pass. A misconfigured group won't silently deactivate your
  whole company.
</Note>

### Provisioning webhooks

Rippling notifies Risotto of employee lifecycle changes as they happen, so terminations don't wait for the overnight sync:

| Event | Effect in Risotto |
| - | - |
| `employee.created` | Adds the employee to the roster |
| `employee.updated` | Refreshes the stored details for a tracked employee |
| `employee.terminated` | Marks the employee inactive; People Actions stop |
| `employee.deleted` | Marks the employee inactive; People Actions stop |
| `company.deleted` | Removes the connection and tears down the roster |

Webhooks are configured on the Risotto app itself, and your Rippling provisioning rules control which employees generate events.

<Note>
  Rippling delivers webhooks with a delay of roughly five minutes.
</Note>

### Employee data lookup

When an employee asks Risotto for their own HR data, Risotto calls Rippling live and reads only the fields that request needs.

To find the employee, Risotto matches their email against Rippling's `work_email`. The resolved Rippling worker ID is stored on the employee's Risotto identity so later requests skip the lookup.

### Time off request

The only flow that writes to Rippling. When an employee asks for time off, Risotto confirms the details with them first, then creates the request in Rippling with status `pending`, where it enters your normal approval flow. Risotto never approves anything.

### Trigger a sync manually

To force an immediate roster sync without waiting for the overnight run, go to **Settings → People → Connect**, open the menu on the Rippling row, and click **Sync now**.

The Rippling row reports the result inline:

| Status line | Meaning |
| - | - |
| `Employee sync in progress...` | A sync is running now |
| `Employees last synced <time>` | The last sync succeeded |
| `Last employee sync failed (<cause>)` | The last sync failed; the cause is in parentheses |

<Note>
  The other three flows can't be triggered by hand, and don't need to be.
  Webhooks are sent by Rippling, and employee lookups and time off requests only
  ever run in response to an employee asking.
</Note>

## Data Fields That Sync

Risotto resolves the requesting employee's Rippling worker record by matching their work email, then reads only the fields required to answer that request.

### Employee profile (read)

Pulled from the Rippling `workers` endpoint:

| Rippling field | Used for |
| - | - |
| `work_email` | Primary identifier matched against the requester's email |
| `personal_email` | Fallback key when a synced worker has no work email on file |
| `display_name` | Preferred display name in Risotto responses |
| `title` | Employee profile lookups |
| `department` | Employee profile lookups |
| `location` | Work location lookups |
| `start_date` | Start date lookups |
| `status` | Detecting terminated workers |
| `user.number` | Rehire-stable employee number used to re-link a returning employee |

<Note>
  Live lookups match on `work_email` only. `personal_email` is used as a
  fallback when the roster sync encounters a worker with no work email — so an
  employee whose Slack email matches neither field won't resolve.
</Note>

### Home address (read only)

Read from the worker's `HOME`-typed address record:

| Rippling field | Used for |
| - | - |
| `street_address` | Street address lines |
| `locality` | City |
| `region` | State or province |
| `postal_code` | Postal / ZIP code |
| `country` | Country |

### Time off (read and write)

Rippling stores leave amounts in minutes; Risotto surfaces them in hours.

| Rippling endpoint | Used for |
| - | - |
| `leave-balances` | Current balance and policy type for each plan the employee is assigned to |
| `leave-requests` | Read recent and upcoming time off requests, and submit a new request with status `pending` |

<Note>
  Unlimited PTO policies don't track a running balance, so Risotto surfaces
  those as unlimited rather than a literal number.
</Note>

## Supported Actions

Rippling supports the following [People Actions](/dashboard/settings/people/actions):

<CardGroup>
  <Card title="Get Employee Info" icon="id-card">
    Look up the requesting employee's profile, title, department, work location,
    and start date. Turn it on in [Support agent >
    Context](/dashboard/settings/support-agent/context).
  </Card>

  <Card title="Get Home Address" icon="house">
    View the home address on file for the requesting employee.
  </Card>

  <Card title="Get PTO Balance" icon="calendar-check">
    Retrieve balances for each policy type the employee is assigned to.
  </Card>

  <Card title="Request PTO" icon="calendar-plus">
    Submit a time off request for the requesting employee. Requests are created
    with status `pending` and follow your Rippling approval flow.
  </Card>
</CardGroup>

<Warning>
  **Update Home Address** is not supported for Rippling. The Rippling API does
  not expose address writes, so employee addresses can only be edited in
  Rippling by the employee or an HR admin.
</Warning>

## Terminated employees and rehires

When Rippling marks an employee as terminated or deleted, Risotto receives a webhook and immediately stops [People Actions](/dashboard/settings/people/actions) from running for that employee. Requests from former employees are escalated, even if their Slack account is still active. The daily roster sync catches anyone a missed webhook left behind.

Rehires are handled automatically. Rippling issues a new worker ID when someone returns, so Risotto re-resolves them on their next request or on the next roster sync and reactivates their record.

## Disconnecting

Rippling stays installed on your org until an admin removes it in Rippling. To start, click **Connected** on the Rippling row, then click **Disconnect...**. In the **Disconnect from Rippling?** dialog, click **Continue to Rippling** to uninstall Risotto in the Rippling App Shop.

Uninstalling in Rippling triggers a `company.deleted` webhook, and Risotto then deletes its stored access and refresh tokens and marks every Rippling-sourced employee record inactive.

<Warning>
  Removing the app only in the Risotto dashboard is not enough. Until it's
  uninstalled in Rippling, the connection remains live on Rippling's side.
</Warning>

## FAQs

<AccordionGroup>
  <Accordion title="Can employees look up other people's information?">
    No. Every People Action is scoped to the person making the request. An
    employee can retrieve their own PTO balance or home address, but cannot ask
    Risotto for a colleague's. There is no manager or admin lookup path through
    this integration.
  </Accordion>

  <Accordion title="Can a new hire in Rippling open a ticket in Risotto?">
    Not by itself. A Rippling event updates the roster, but it does not create a
    ticket or start an automation. The Rippling events in the automation trigger
    picker are marked **Soon** and do not run today. To open a ticket for each new
    hire now, create an automation with a [Webhook
    trigger](/dashboard/automations#webhook-trigger). Then call its URL from a
    step in your Rippling onboarding workflow, and let the automation create the
    ticket.
  </Accordion>

  <Accordion title="Can Risotto approve time off, or change anything else in Rippling?">
    No. The only write this integration performs is creating a time off request
    with status `pending`, which then follows your existing Rippling approval
    flow. Risotto cannot approve requests, edit profiles, change addresses, or
    modify payroll.
  </Accordion>

  <Accordion title="Does the employee get asked before Risotto submits a PTO request?">
    Yes. Submitting time off requires an explicit confirmation from the employee
    that is separate from their original message, so a casual mention of time
    off never creates a request on its own.
  </Accordion>

  <Accordion title="Should we enable Get Home Address?">
    That's a judgment call about PII. The action only ever returns the requesting
    employee's own address, and it's read-only. It does mean home addresses
    flow through your ticket source and any external ticket sync. If your policy
    restricts where address data may appear, leave it disabled. Every action is
    independently toggleable, so you can enable PTO features without it.
  </Accordion>

  <Accordion title="How fresh is the data Risotto reports?">
    PTO balances, job details, and addresses are read live from Rippling at the
    moment of the request.
  </Accordion>

  <Accordion title="How long after a termination does Risotto stop responding?">
    Rippling sends the termination webhook with a delay of roughly five minutes.
    For an immediate cutoff, click **Sync now**.
  </Accordion>

  <Accordion title="Can we connect Rippling to more than one Risotto org?">
    No. A Rippling company maps to exactly one Risotto org, so that webhooks
    route unambiguously. To move the connection, disconnect from the first org
    before installing in the second.
  </Accordion>

  <Accordion title="What about contractors and international workers?">
    Scope is set by your Rippling provisioning rules, not by worker type. Anyone
    those rules place in the provisioning group is in scope; anyone they exclude
    is not. If contractors should be able to self-serve, confirm your Rippling
    provisioning rules include them.
  </Accordion>

  <Accordion title="Are half-days and part-time schedules supported?">
    Yes. Risotto sends the hours per day with the request when they differ from
    a standard eight-hour day, so part-day requests and part-time schedules are
    submitted correctly.
  </Accordion>

  <Accordion title="Is there an audit trail?">
    Yes. Risotto records org events for manual sync triggers, employee
    provisioning and deactivation, and the app uninstall.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Install fails: “Please disconnect Rippling from your other Risotto org”">
    This Rippling company is already connected to a different Risotto org.
    Disconnect it there first, then retry.
  </Accordion>

  <Accordion title="Install fails: “The Rippling install session expired”">
    The install is time-limited, and a slow sign-in during the handoff can let
    it lapse. Retry the install from the Risotto app page in Rippling.
  </Accordion>

  <Accordion title="Install fails: “Could not complete the Rippling install”">
    Rippling rejected the credential exchange. Retry the install. If it keeps
    failing, confirm you're signed in as a Rippling admin and contact Risotto
    support.
  </Accordion>

  <Accordion title="Sync failed: no PROVISIONING supergroup found in Rippling">
    Rippling has no provisioning group for Risotto to read, which almost always
    means account provisioning hasn't been configured for the Risotto app yet.
    Set up provisioning rules in Rippling, then click **Sync now**.
  </Accordion>

  <Accordion title="Sync failed: Rippling connection needs to be reconnected">
    Risotto's stored credentials can no longer be refreshed and Rippling data is
    unavailable until an admin reconnects. Risotto notifies org admins when this
    happens. Reinstall from **Settings → People → Connect**; syncing is blocked
    until you do.
  </Accordion>

  <Accordion title="Sync failed: Rippling API request failed, or timed out">
    A transient Rippling API problem — a rate limit, a temporary outage, or a
    roster large enough to exceed the time limit. The next daily sync retries
    automatically; **Sync now** retries immediately.
  </Accordion>

  <Accordion title="An employee is told they aren't found in the HR system">
    Risotto couldn't match them to a Rippling worker. Check, in order:

    1. Their Slack email matches their Rippling `work_email`.
    2. Rippling's provisioning rules include them, so they're in the group Risotto reads.
    3. They aren't marked terminated in Rippling.
    4. A roster sync has run since they were added — click **Sync now**.
  </Accordion>

  <Accordion title="Risotto isn't taking any HR actions at all">
    Confirm the actions are actually enabled. Installing the integration does
    not enable anything on its own — each action must be turned on under
    **Settings → People → Actions**.
  </Accordion>

  <Accordion title="An employee's PTO request was rejected by Rippling">
    Rippling validates requests against its own rules such as insufficient balance,
    blackout dates, policy restrictions, or overlapping requests. Risotto relays
    the reason Rippling gives. The employee can submit in Rippling directly if
    the rule needs an exception.
  </Accordion>
</AccordionGroup>


# Workday
Source: https://docs.tryrisotto.com/dashboard/settings/people/connect/workday

Connect Workday as your HRIS to power employee self-service

Connect Workday as your HRIS to power employee self-service. Once connected, Risotto can look up employee information, retrieve PTO balances, and more. These actions are controlled by the [People Actions](/dashboard/settings/people/actions) settings.

## Connect from the Dashboard

Open **Settings → People → Connect** and click **Connect** on the **Workday** row. The configuration panel is titled "Configure the Risotto Workday integration for HR management using OAuth 2.0 JWT bearer authentication" and has two parts:

* An **Instructions** pane on the left with a **Generate certificate & private key** button and the Workday setup steps.
* A form on the right with the required fields listed below, a **Test connection** button, and a **Save** button.

<Steps>
  <Step title="Generate the certificate and private key">
    Click **Generate certificate & private key**. Risotto creates a self-signed certificate and PKCS#8 private key (RSA 2048, roughly 10-year validity) and displays the certificate PEM for you to copy into your Workday tenant.

    Each click creates a new key pair and replaces the previous one. If you click the button again, put the new certificate in Workday too. Workday refuses the connection if its public key does not match the key that Risotto saved.
  </Step>

  <Step title="Register the public key in Workday">
    Run the **Create x509 Public Key** task in Workday. Paste the certificate PEM
    from the previous step and set **Name** to `risotto_workday_integration_key`.
  </Step>

  <Step title="Create the Integration System User">
    Create an **Integration System User (ISU)** and assign the domain security
    and/or user security groups described under [ISU Security
    Configuration](#isu-security-configuration) so the user can read and update
    the worker data Risotto uses.
  </Step>

  <Step title="Fill in the connection form and save">
    Enter the required information below and click **Save**.
  </Step>
</Steps>

## Required Information

To connect Workday, provide:

* **Integration System Username** (required): The Integration System User account Risotto will authenticate as, for example `integration_user`
* **Client ID** (required): The API client ID, a UUID in the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
* **Tenant URL** (required): The host of your Workday API, without a path. Copy it from the **Token Endpoint** of the Risotto API client in Workday (run **View API Clients**).
* **Tenant Name** (required): The name of your Workday tenant. It is the part of the **Token Endpoint** after `/ccx/oauth2/`. Only letters, numbers, underscores, and hyphens are allowed.
* **X.509 Public Key**: Generated from the Risotto dashboard and uploaded to Workday

Risotto builds the token URL as `<Tenant URL>/ccx/oauth2/<Tenant Name>/token`. This URL must be the same as the **Token Endpoint** in Workday. For example, if the Token Endpoint is `https://wd5-services1.myworkday.com/ccx/oauth2/acme/token`, enter:

* **Tenant URL**: `https://wd5-services1.myworkday.com`
* **Tenant Name**: `acme`

<Note>
  Many Workday hosts start with a data center prefix such as `wd5-`, but some do
  not. Copy the host exactly as the Token Endpoint shows it. Do not add or
  remove a prefix.
</Note>

## ISU Security Configuration

The ISU must have domain security in Workday, and the API client must have matching functional area scopes. Without these, Risotto cannot read or write the corresponding worker data, even if the action is toggled on in the dashboard.

When a domain is missing, Workday refuses the request with a permission error. The tools **Get Workday Employee Info**, **Get Workday Home Address**, **Get Workday Time Off Balance**, and **Update Workday Home Address** then tell the agent that Workday is not configured correctly, and your admins get one alert for each tool: "Workday denied access to this data. Make sure the integration system user's security group has the required domain permissions in Workday." Add the missing domain to the ISU's security group in Workday.

### Domain Security Policies

Assign these to the ISU's integration security group. Domain names can vary slightly by tenant, search **Domain Security Policies** in Workday for the closest match.

**Worker lookup**

| Domain | Permission | Purpose |
| - | - | - |
| Worker Data: Public Worker Reports | Get | WQL queries to resolve workers by email |
| Worker Data: Workers | Get | Retrieve worker details (job title, manager, org) |
| Worker Data: Current Staffing Information | Get | Resolve person ID from worker ID via Staffing service |
| Worker Data: All Positions | Get | Current and historical position details |
| Staffing | Get | General staffing service access |
| System: Workday Query Language | Get | Execute WQL queries |
| System: Worker Event History | Get | Read worker event history |

**Personal data**

| Domain | Permission | Purpose |
| - | - | - |
| Person Data: Personal Data | Get | Get personal data |
| Person Data: Personal Information | Get | Get personal information fields |

**Home address**

| Domain | Permission | Purpose |
| - | - | - |
| Person Data: Home Contact Information | Get and Put | Read home addresses and update them within a change event |
| Person Data: Home Address | Get and Put | Secures *Change Home Contact Information (REST Service)* |
| Self-Service: Home Address | Get and Put | Secures *Change Home Contact Information (REST Service)* initiated on behalf of the worker |
| Person Data: Work Contact Information | Get | Read work contact information |

**Time off and absence**

| Domain | Permission | Purpose |
| - | - | - |
| Worker Data: Time Off | Get and Put | PTO balances, time off entries, eligible types, and submitting time off requests |
| Absence Management | Get and Put | Absence management operations |
| Worker Data: Absence Balances | Get | Retrieve PTO balances |
| Self-Service: Time Off and Leave Balances | Get | Retrieve time off and leave balances |

### API Client Scopes

When you register the API client in Workday, grant these functional areas:

* **Staffing**: worker lookup, initiate home contact information changes
* **Personal Data**: read personal information
* **Contact Information**: read and update home addresses
* **Time Off and Leave**: PTO balances, time off entries, eligible types, and time off requests
* **Absence Management**: PTO balances and time off requests
* **System**: WQL support and REST API routing
* **Tenant Non-configurable**: global scope required for WQL and People resources

<Warning>
  Note: Once these security domains and API scopes have been updated, run the
  **Activate Pending Security Policy Changes** task to ensure changes are
  applied.
</Warning>


# Dashboard Authentication Setup
Source: https://docs.tryrisotto.com/guides/dashboard-authentication

Configure Single Sign-On (SSO) for your Risotto dashboard using enterprise identity providers

# Dashboard Authentication Setup

Configure Single Sign-On (SSO) for your Risotto dashboard to enable secure, seamless authentication using your organization's existing identity provider.

<Tip>
  **Contact Risotto Support**: SSO configuration requires enablement by Risotto
  support. Contact your account representative or
  [support@tryrisotto.com](mailto:support@tryrisotto.com) to activate SSO for
  your organization before beginning setup.
</Tip>

## Prerequisites

Before configuring SSO, ensure you have:

* **Administrative access** to your identity provider
* **SSO enabled** by Risotto support team

<Info>
  **Who this affects.** Dashboard SSO only applies to the admins and agents who
  sign in to the Risotto dashboard. Employees who request help through Slack or
  Microsoft Teams never sign in to Risotto, so they are already covered by your
  identity provider's own login and MFA. You can set up dashboard SSO at any
  point, including during a pilot; there is no need to wait for go-live.
</Info>

## Supported Identity Providers

<AccordionGroup>
  <Accordion title="Okta SAML Configuration">
    ### Overview

    Configure SAML-based authentication using Okta Workforce Identity to allow your users to sign into the Risotto dashboard with their Okta credentials.

    ### Supported Features

    The Risotto SAML integration supports **SP-initiated SSO**. Users sign in from the Risotto dashboard and are redirected to Okta to authenticate.

    **IdP-initiated SSO** (launching Risotto from the Okta dashboard tile) is off by default. If your team wants it, ask Risotto Support to enable it when you share your metadata in Step 4. Without it, the Okta tile returns a `RelayState parameter is missing` error.

    ### Step 1: Request Risotto Support to Enable SSO

    1. Reach out to [Risotto Support](mailto:support@tryrisotto.com) and request to enable Dashboard SSO via Okta.
    2. Risotto Support will provide your **`risotto_org_id`**.

    Your `risotto_org_id` is the ID of the SSO connection that Risotto creates for your organization. It is not your Okta domain, and it is not the organization ID that the Risotto dashboard shows. Okta uses it to link the Risotto catalog app to your account. You enter this value when adding the app in Step 2, so keep it on hand.

    ### Step 2: Add the Risotto App from the Okta Catalog

    1. Sign in to your **Okta Admin Console**
    2. Navigate to **Applications** > **Applications**
    3. Click **Browse App Catalog**
    4. Search for **Risotto** and select it from the results
    5. Click **Add Integration**
    6. In the app's configuration settings, enter the **`risotto_org_id`** that Risotto Support provided in Step 1

    Aside from your `risotto_org_id`, the Risotto catalog integration is preconfigured with all required SAML settings, attribute statements, and Name ID format. There is no other manual SAML configuration to complete — you only need to share your metadata with Risotto (see Step 4).

    ### Step 3: Assign Users and Groups

    1. Navigate to the **Assignments** tab of your Risotto app
    2. Click **Assign** > **Assign to Groups** or **Assign to People**
    3. Select the users/groups who should have access to Risotto
    4. Click **Done**

    ### Step 4: Share Metadata URL with Risotto Support

    1. In Okta, go to the **Sign On** tab of your Risotto app
    2. Copy the **Metadata URL** from the SAML setup instructions
    3. Share the **Metadata URL** with the Risotto team
    4. Request the Risotto team to enforce SSO for your organization

    ### Testing

    Test the integration by:

    1. Opening an incognito/private browser window
    2. Navigating to your Risotto dashboard
    3. Clicking **Sign in with Okta**
    4. Verifying successful authentication and access
  </Accordion>

  <Accordion title="Google Workspace Configuration">
    ### Overview

    Google Workspace offers two authentication methods for the Risotto dashboard: **Sign in with Google** (OAuth) for simple setups, or **SAML** for enterprise requirements.

    ### Option 1: Sign in with Google (Recommended)

    **Best for**: Organizations wanting quick setup with Google OAuth

    1. Contact [Risotto Support](mailto:support@tryrisotto.com) and request Google sign-in for the Risotto dashboard.
    2. Share your **Google Workspace domain** with Risotto Support.
    3. Risotto Support sets up and enables the connection.

    **Benefits of OAuth**:

    * Automatic user provisioning
    * Built-in MFA support through Google
    * No certificate management required

    ### Option 2: Google SAML Configuration

    **Best for**: Organizations requiring SAML compliance or advanced attribute mapping

    ### Step 1: Request a SAML Connection from Risotto

    1. Contact [Risotto Support](mailto:support@tryrisotto.com) and request a Google SAML connection.
    2. Share your **email domain** with Risotto Support.
    3. Risotto Support creates the connection and sends you the **Single Sign-On URL** and **Audience URI**.

    ### Step 2: Configure SAML App in Google Admin

    1. Sign in to your **Google Admin Console**
    2. Navigate to **Apps** > **Web and mobile apps**
    3. Click **Add app** > **Add custom SAML app**

    **App Details:**

    * **App name**: `Risotto Dashboard`
    * **Description**: `SSO access to Risotto IT automation platform`

    **Google Identity Provider Details:**

    * Download the **certificate** and note the **SSO URL**

    **Service Provider Details:**

    * **ACS URL**: Use Single Sign-On URL from Risotto
    * **Entity ID**: Use Audience URI from Risotto
    * **Start URL**: Leave blank
    * **Signed response**: Checked
    * **Name ID**: Basic Information > Primary email

    **Attribute Mapping:**

    | Google Directory attributes | App attributes |
    | - | - |
    | Primary email | mail |
    | First name | firstName |
    | Last name | lastName |

    ### Step 3: Complete Configuration

    1. Send the Google SAML **certificate** and the Google **SSO URL** to Risotto Support.
    2. Risotto Support completes and enables the connection.
  </Accordion>

  <Accordion title="Microsoft Entra ID Configuration">
    ### Overview

    Configure SAML-based authentication using Microsoft Entra ID (formerly Azure AD) to enable secure dashboard access for your organization.

    ### Step 1: Request a SAML Connection from Risotto

    1. Contact [Risotto Support](mailto:support@tryrisotto.com) and request a Microsoft Entra ID SAML connection.
    2. Share your **email domain** with Risotto Support.
    3. Risotto Support creates the connection and sends you the **Single Sign-On URL** and **Audience URI**.

    ### Step 2: Configure Enterprise Application in Entra ID

    1. Sign in to the **Azure Portal**
    2. Navigate to **Microsoft Entra ID** > **Enterprise Applications**
    3. Click **New application** > **Create your own application**
    4. Name it `Risotto Dashboard` and select **Integrate any other application**

    **Single Sign-On Configuration:**

    1. Select **SAML** as the SSO method
    2. Click **Edit** in the Basic SAML Configuration section

    **Basic SAML Configuration:**

    * **Identifier (Entity ID)**: Use Audience URI from Risotto
    * **Reply URL (Assertion Consumer Service URL)**: Use Single Sign-On URL from Risotto
    * **Sign on URL**: Your Risotto dashboard URL
    * **Relay State**: Leave blank

    **User Attributes & Claims:**

    | Claim name | Source attribute |
    | - | - |
    | `emailaddress` | `user.mail` |
    | `givenname` | `user.givenname` |
    | `surname` | `user.surname` |

    ### Step 3: Assign Users and Groups

    1. Navigate to **Users and groups** in your Enterprise Application
    2. Click **Add user/group**
    3. Select users or groups that should have Risotto access
    4. Click **Assign**

    ### Step 4: Complete Risotto Configuration

    1. In Azure, go to **Single sign-on** > **SAML Certificates**
    2. Download the **Certificate (Base64)**
    3. Copy the **Login URL**
    4. Send the **certificate** and the **Login URL** to Risotto Support.
    5. Risotto Support completes and enables the connection.
  </Accordion>
</AccordionGroup>

## User Management

### Provisioning

Risotto does not create accounts automatically through SSO — Just-In-Time (JIT) provisioning is not supported. Users must already have a Risotto account before they can sign in, so invite them to your Risotto organization first. Once a user exists, SSO matches them by email address and signs them in with their existing Risotto profile and permissions.

SCIM provisioning is not supported. Manage dashboard users from the Risotto dashboard; see [Invite Users](/guides/invite-users).

<Tip>
  Recommended order: create your Risotto organization and invite your dashboard
  users first (email or Google sign-in is fine to start), then layer SSO on top.
  Ask Risotto Support to enforce SSO-only sign-in once everyone has tested it.
</Tip>

### Deprovisioning

<Warning>
  **Account Suspension**: Users removed from SSO assignments in your identity
  provider will lose access to Risotto. Ensure proper coordination between
  identity management and Risotto administration.
</Warning>


# Microsoft Teams App Setup
Source: https://docs.tryrisotto.com/guides/teams/teams-app

Connect Risotto to Microsoft Teams and deploy the app to your organization

# Connect Risotto to MS Teams

Connect Risotto to your Microsoft Teams environment and deploy the official Risotto app so it's available to everyone in your organization.

<Info>
  Unlike Slack, Risotto uses an official Microsoft Teams app. There is no custom
  or self-hosted app to build.
</Info>

<Note>
  **Before you begin**, make sure you have:

  * Admin access to the Microsoft Teams admin center ([admin.teams.microsoft.com](https://admin.teams.microsoft.com))
  * Access to the Risotto dashboard
</Note>

## Connect Microsoft Teams in Risotto

<Steps>
  <Step title="Open Settings">
    In the Risotto dashboard ([dashboard.tryrisotto.com](https://dashboard.tryrisotto.com)),
    open **Settings**.
  </Step>

  <Step title="Select Integrations">
    Go to **Integrations -> All** and find Microsoft Teams under the **Chat**
    section.
  </Step>

  <Step title="Connect Microsoft Teams">
    Click **Connect** beside Microsoft Teams. You'll be forwarded to a Microsoft
    consent screen. Make sure you're logged in as a user with admin privileges.
  </Step>

  <Step title="Consent to the requested permissions">
    Review and accept the requested permission scopes. Granting consent gives Risotto everything it needs to operate in your Microsoft Teams instance.
  </Step>
</Steps>

## Install and deploy the app

<Steps>
  <Step title="Open the Teams admin center">
    Go to [admin.teams.microsoft.com](https://admin.teams.microsoft.com) and sign in with an admin account.
  </Step>

  <Step title="Go to Apps">
    Navigate to **Teams apps → Manage apps** in the admin center.
  </Step>

  <Step title="Install the Risotto app">
    Find the Risotto app and install it.
  </Step>

  <Step title="Deploy the app for everyone">
    Deploy the Risotto app so it's available to all users across your
    organization.
  </Step>

  <Step title="Wait for the app to propagate">
    Allow about **5 minutes** for the app to become available across Microsoft Teams before continuing.
  </Step>
</Steps>

<Warning>
  Microsoft Teams can take a few minutes to make a newly deployed app available.
  If the Risotto app doesn't appear yet, wait a few minutes and refresh before
  continuing.
</Warning>

## Next Steps

Once the app is deployed and available, continue to [Microsoft Teams Channel Setup](/guides/teams/teams-helpdesk) to add the Risotto bot to your team and start handling requests.


# Microsoft Teams Channel Setup
Source: https://docs.tryrisotto.com/guides/teams/teams-helpdesk

Add the Risotto bot to your team and configure it to handle requests

# Microsoft Teams Channel Setup

Add the Risotto bot to your team in Microsoft Teams and configure it as a request source so users can submit requests and Risotto can respond.

<Steps>
  <Step title="Add the Risotto bot to your team">
    In the Microsoft Teams desktop app, add the Risotto bot to the team where you want users to submit requests.
  </Step>

  <Step title="Open Request Sources in Risotto">
    In the Risotto dashboard, open **Settings → Request Sources**. Under
    **Microsoft Teams channels**, select the channel you want to use.
  </Step>

  <Step title="Turn off Silent channel">
    Make sure **Silent channel** is turned off so Risotto replies in the channel.
    When **Silent channel** is on, Risotto stays silent and only engages when a
    user @mentions it.
  </Step>

  <Step title="Verify your settings">
    Confirm the channel is enabled as a request source and that **Silent channel** is configured the way you want.
  </Step>
</Steps>

## Test Your Setup

After adding the bot and configuring the channel:

1. **Tag the Risotto bot** in the channel and ask a simple question.
2. **Confirm a ticket is created** — Risotto should respond and open a ticket for your request.
3. **Verify the ticket is handled as expected** — for example, that it escalates when it can't be resolved automatically.

## Next Steps

Once Microsoft Teams is set up and tested:

1. Complete your [organization setup](/guides/initial/org-setup)
2. Begin testing Risotto with your team
3. Configure additional settings as needed for your organization


# MCP Server
Source: https://docs.tryrisotto.com/integrations/mcp-server

Connect Claude Desktop, Cursor, and other MCP clients to Risotto to work with tickets, knowledge, runbooks, automation tools, access rules, and settings.

# Risotto MCP Server

Risotto exposes a [Model Context Protocol](https://modelcontextprotocol.io) server so MCP-compatible clients (Claude Desktop, Cursor, ChatGPT, and custom agents) can call into your Risotto workspace. The server has 120 tools. You can work with tickets, knowledge, users, departments, runbooks, automation tools, access rules, and organization settings. See [Available tools](#available-tools) for the full list.

Clients authenticate with **OAuth 2.1**. Your client runs a standard browser-based authorization flow, and each user signs in with their own Risotto identity, so tool calls are attributed and audited per person. Claude Desktop, Claude Code, Cursor, ChatGPT, the MCP Inspector, and any client that ships a built-in OAuth UI connect this way. Risotto API keys are not an authentication method for the MCP server.

<Info>
  OAuth clients self-register with Risotto the first time they connect — there
  is no "create OAuth client" step in the dashboard. You only need the server
  URL.
</Info>

## Prerequisites

* A Risotto account in the organization. Every organization role can connect. Your role limits the scopes that you can grant (see [Scopes and organization roles](#scopes-and-organization-roles)).
* An MCP-compatible client. OAuth requires a client that supports OAuth 2.1 + Dynamic Client Registration (Claude Desktop, recent Cursor, MCP Inspector, or any spec-compliant client).

## Find your MCP server URL

Each Risotto organization has its own MCP server URL of the form:

```text theme={null}
https://api.tryrisotto.com/o/<org_id>/mcp
```

Copy your organization's specific URL from [**Settings → Integrations → MCP**](https://dashboard.tryrisotto.com/settings/integrations/mcp) in the dashboard.

## Connect with OAuth

<Note>
  Org Admins and Managers can grant every scope. A Member can grant only the
  Member scopes. See [Scopes and organization
  roles](#scopes-and-organization-roles).
</Note>

<Steps>
  <Step title="Add the MCP server to your client">
    Most MCP clients only need the server URL — they handle registration and the consent flow automatically.

    <Tabs>
      <Tab title="Claude Desktop">
        Edit your Claude Desktop config file:

        * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
        * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

        ```json theme={null}
        {
          "mcpServers": {
            "risotto": {
              "transport": {
                "type": "http",
                "url": "YOUR_MCP_SERVER_URL"
              }
            }
          }
        }
        ```

        Replace `YOUR_MCP_SERVER_URL` with the URL from your dashboard. No client ID, client secret, or token URL is needed — Claude Desktop discovers everything from the server.

        Restart Claude Desktop after saving.
      </Tab>

      <Tab title="Cursor">
        Open **Cursor Settings → MCP → Add MCP server** and paste your MCP server URL from the dashboard.

        Save. Cursor will trigger the OAuth flow on first use.
      </Tab>

      <Tab title="ChatGPT">
        ChatGPT connects to Risotto as a custom MCP connector.

        <Note>
          Custom connectors require a ChatGPT **Pro, Team, or Enterprise** plan with **developer mode** enabled.
        </Note>

        In ChatGPT, go to **Settings → Connectors → Add custom connector** and paste your MCP server URL from the dashboard.

        ChatGPT runs the OAuth flow automatically — sign in with your Risotto account and approve the scopes you want. Risotto's tools then appear in ChatGPT's tool picker.
      </Tab>

      <Tab title="MCP Inspector">
        ```bash theme={null}
        npx @modelcontextprotocol/inspector YOUR_MCP_SERVER_URL
        ```

        The Inspector opens a browser tab for consent, then exposes a JSON-RPC console for poking at the server directly.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Sign in and grant scopes">
    The first time the client connects, a browser tab opens to a Risotto consent screen. Sign in with the same account you use for the dashboard and review the scopes the client is requesting. Clear the checkbox next to a scope to leave it out of the grant, then click **Allow**.

    The scopes you approve at this screen bound that specific client's access — they don't change your overall account permissions. The screen lists only the requested scopes that your organization role can hold.
  </Step>

  <Step title="Use the tools">
    Risotto's tools now appear in the client's tool picker. The access token issued at consent is refreshed automatically; you won't be re-prompted unless you revoke the client or the refresh window lapses.
  </Step>
</Steps>

### Available scopes

OAuth clients request scopes at consent time. A scope grants the tools listed under it in [Available tools](#available-tools).

| Scope | Grants |
| - | - |
| `tickets:read` | List and read tickets, comments, ticket insights, and ticket field definitions |
| `tickets:write` | Create, update, resolve, and escalate tickets, and add comments |
| `tickets:delete` | Reserved. No MCP tool uses this scope yet |
| `knowledge:read` | Search indexed knowledge, list knowledge sources, check a document's index |
| `users:read` | Find users and read their profiles and groups |
| `departments:read` | List departments (ID and name only without `config:read`) |
| `departments:write` | Create departments and change department settings |
| `runbooks:read` | Read runbooks and a ticket's runbook history |
| `runbooks:write` | Create, update, duplicate, and delete runbooks and forms, and read drafts, revisions, templates, forms, and the authoring guide |
| `tools:read` | List automation tools and tool templates, read script drafts and runs |
| `tools:write` | Create and update automation tools and script tools, set tool approval |
| `tools:execute` | Run and test automation tools and scripts |
| `custom_api_sources:read` | List custom API sources and browse the shipped API templates |
| `custom_api_sources:write` | Create custom API sources and stage, test, and promote endpoint drafts |
| `external_mcp_servers:read` | List connected external MCP servers |
| `external_mcp_servers:write` | Connect external MCP servers and import their tools |
| `applications:read` | List the applications that requestors can ask access to |
| `access_rules:read` | List access rules |
| `access_rules:write` | Create and update applications and access rules |
| `settings:read` | Read organization settings, request sources, and the IdP config |
| `settings:write` | Update organization settings, request routing, ticket fields, and Okta config |
| `artifacts:read` | List and read artifact pages |
| `artifacts:write` | Delete artifact pages |
| `audit:read` | Read the configuration audit log |
| `config:read` | Read Assistant settings, full department settings, and the automation opportunities report |
| `config:write` | Update Assistant settings |
| `triggers:read` | Reserved. No MCP tool uses this scope yet |
| `triggers:write` | Reserved. No MCP tool uses this scope yet |

<Tip>
  Follow least privilege. For a read-only assistant, approve `tickets:read`,
  `knowledge:read`, `users:read`, `departments:read`, `runbooks:read`, and
  `tools:read`. Add write or execute scopes only when a workflow needs them.
</Tip>

#### Scopes and organization roles

Your organization role limits the scopes that a client can hold:

* **Org Admin and Org Manager** can hold every scope.
* **Member** can hold `tickets:read`, `tickets:write`, `knowledge:read`, `users:read`, `departments:read`, `runbooks:read`, and `applications:read`.

At consent, a Member sees only the requested scopes in this list. If none of the requested scopes is in the list, the client gets `access_denied`. Risotto checks the role on every request. When an admin changes your role, your tokens get the scopes of the new role within 5 minutes. A user who leaves the organization gets `403`.

A Member also has these limits:

* A Member can act only as themselves. Risotto refuses a `create_ticket` for another requestor ("You can create tickets only for yourself"), an `add_comment` as another author ("You can comment only as yourself"), and a `search_knowledge` or `check_document_index_status` on behalf of another user ("You can search only with your own access").
* `search_knowledge` with a `dept_id` works only for a department where the Member can read tickets. Without `dept_id`, it searches only documents shared with the whole organization.
* `list_runbooks` and `get_runbook` return the org-wide runbooks and the runbooks of the Member's departments.

<Note>
  Ticket access via MCP respects the authenticated user's department membership
  and role, the same as the dashboard and chat — a `tickets:read` scope doesn't
  grant visibility into tickets outside the departments that user belongs to.
</Note>

### Manage authorized clients

From [**Settings → Integrations → MCP**](https://dashboard.tryrisotto.com/settings/integrations/mcp) in the dashboard you can:

* See every OAuth client that has registered against your organization, including the IP it was registered from and when it last made a request.
* Revoke a client — invalidates all of its tokens immediately. The client will be prompted to sign in again on its next request.

Revoking an OAuth client only affects that one client. Other authorized clients keep working.

## Available tools

The server registers 120 tools. Each tool needs one scope. `tools/list` returns only the tools whose scope your credential holds, with their input schemas. For example, a Member sees only the tools of the Member scopes, and an API key with narrow scopes sees only the tools of those scopes. Risotto also checks the scope when you call a tool, so a call to a tool outside your granted scopes fails with a missing-scope error.

Tool names below are the values you pass in `tools/call`. The dashboard Assistant is built on the same tools.

Where a ticket tool takes a `ticket_id`, you can pass the Risotto key (for example `IT-123`) or the key of the synced ticket in your ticketing system (for example the Jira key `ENG-123`). Risotto tries the Risotto key first, then the synced key. If more than one ticket has the same synced key, Risotto uses the newest ticket. Ticket results include `external_ticket_id` and `external_ticket_url`. Both are `null` when the ticket is not synced. `list_tickets` has no filter for the synced key, but its `search` argument matches the synced key.

Ticket results also include `priority`, as `{ value, is_suggested }` or `null`. `value` is `low`, `medium`, `high`, or `urgent`. `is_suggested` is `true` when the value is the priority that the AI suggested, and `false` when a person set it. The ticket tools cannot change the priority. See [Ticket priority](/integrations/webhooks#ticket-priority).

To find tickets about a topic, pass `search` to `list_tickets`. The search is not case-sensitive. It matches the ticket title, public comments, the requestor's email, the assignee's name, the name of the Slack channel where the ticket started, the synced key, and the ticket number (`123` or `IT-123`). Risotto combines `search` with the other filters. The dashboard **Search tickets** box matches the same fields.

<AccordionGroup>
  <Accordion title="Tickets and comments (8 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `list_tickets` | List, filter, and search tickets. Returns up to 100 tickets per page. | `tickets:read` |
    | `get_ticket` | Get one ticket with its comments and workflow state. | `tickets:read` |
    | `list_ticket_comments` | List the comments on a ticket. | `tickets:read` |
    | `create_ticket` | Create a ticket. The agent processes it like a ticket from chat. | `tickets:write` |
    | `update_ticket` | Update ticket fields. Only the fields you pass change. | `tickets:write` |
    | `add_comment` | Add a comment to a ticket. | `tickets:write` |
    | `resolve_ticket` | Mark a ticket as resolved. Also resolves the synced external ticket. | `tickets:write` |
    | `escalate_ticket` | Escalate a ticket to human support. Sends a Slack notification and stops the agent. | `tickets:write` |
  </Accordion>

  <Accordion title="Ticket insights (7 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `get_ticket_runbook_match_history` | Show which runbooks matched a ticket and why. | `tickets:read` |
    | `get_ticket_retrieval_history` | Show the knowledge that Risotto retrieved for a ticket. | `tickets:read` |
    | `get_ticket_agent_activity` | Show the agent's steps on a ticket in order. | `tickets:read` |
    | `list_ticket_runbook_history` | List the runbooks matched to a ticket and whether the agent followed them. | `runbooks:read` |
    | `get_automation_opportunities` | Report the requests Risotto could still automate, ranked by ticket volume. Also needs `tickets:read`. | `config:read` |
    | `list_ticket_custom_fields` | List the additional ticket fields defined for the organization. | `tickets:read` |
    | `create_ticket_custom_field` | Create an additional ticket field in a department. | `settings:write` |
  </Accordion>

  <Accordion title="Knowledge (3 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `search_knowledge` | Search indexed knowledge with semantic and keyword retrieval. | `knowledge:read` |
    | `list_knowledge_sources` | List the connected knowledge sources and their index IDs. | `knowledge:read` |
    | `check_document_index_status` | Check whether a document is in the index, by URL or title. | `knowledge:read` |
  </Accordion>

  <Accordion title="Users (3 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `find_users` | Search users by name or email. | `users:read` |
    | `get_user_profile` | Get a user's profile from the identity provider. | `users:read` |
    | `get_user_groups` | Get the identity provider groups a user belongs to. | `users:read` |
  </Accordion>

  <Accordion title="Departments and Tier 2 Assistant (10 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `list_departments` | List departments with descriptions, ticket prefixes, and member counts. Without `config:read`, returns only the ID and name. | `departments:read` |
    | `get_department` | Read every setting of one department. Without `config:read`, returns only the ID and name. | `departments:read` |
    | `create_department` | Create a department from a name and a description. | `departments:write` |
    | `update_department_setting` | Set one department setting, such as the name or description. | `departments:write` |
    | `update_department_ticket_sync_setting` | Set one Ticket Sync toggle for the department's external ticketing system. | `departments:write` |
    | `set_department_ticket_prefix` | Set the ticket prefix, for example `IT` in `IT-123`. | `departments:write` |
    | `set_department_agent_channel` | Set the Slack channel where Risotto posts escalations for the department. | `departments:write` |
    | `set_department_escalation_contact` | Set the person Risotto notifies when a ticket escalates. | `departments:write` |
    | `get_tier_2_assistant_config` | Read a department's Assistant settings: auto start and the investigation and execution instructions. | `config:read` |
    | `update_tier_2_assistant_config` | Set a department's Assistant auto start, investigation instructions, or execution instructions. Omitted settings stay unchanged. | `config:write` |
  </Accordion>

  <Accordion title="Runbooks, templates, and forms (17 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `list_runbooks` | List and filter runbooks. | `runbooks:read` |
    | `get_runbook` | Get a runbook's current version: conditions, instructions, and tool references. | `runbooks:read` |
    | `get_runbook_draft` | Get a runbook's pending draft revision. | `runbooks:write` |
    | `list_runbook_revisions` | List every version of a runbook, newest first. | `runbooks:write` |
    | `get_runbook_authoring_guide` | Get the runbook authoring guide as Markdown. | `runbooks:write` |
    | `create_runbook` | Create a runbook. It is active and indexed immediately. | `runbooks:write` |
    | `update_runbook` | Update one or more fields on a runbook. | `runbooks:write` |
    | `upsert_runbook_draft` | Stage or replace a pending draft revision on a runbook. | `runbooks:write` |
    | `duplicate_runbook` | Copy a runbook. The copy starts disabled with " (Copy)" in its title. | `runbooks:write` |
    | `delete_runbook` | Soft-delete a runbook. The version history is kept. | `runbooks:write` |
    | `list_runbook_templates` | List the curated runbook templates and whether your tools are ready for them. | `runbooks:write` |
    | `get_runbook_template` | Get a runbook template with its content. | `runbooks:write` |
    | `list_forms` | List the structured-input forms, newest first. | `runbooks:write` |
    | `get_form` | Get a form's fields and the runbooks that reference it. | `runbooks:write` |
    | `create_form` | Create a form for runbooks to collect answers from requestors. | `runbooks:write` |
    | `update_form` | Update a form. Omitted arguments stay unchanged. | `runbooks:write` |
    | `delete_form` | Delete a form. | `runbooks:write` |
  </Accordion>

  <Accordion title="Automation tools and scripts (17 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `list_tools` | List the organization's automation tools with their parameter schemas. | `tools:read` |
    | `list_tool_templates` | List the tool templates you can create a tool from. | `tools:read` |
    | `create_tool` | Create an automation tool from a template. | `tools:write` |
    | `update_tool` | Update a tool's enabled state, name, description, or approval setting. | `tools:write` |
    | `configure_tool_approval` | Record how executions of a tool must be approved. | `tools:write` |
    | `request_tool_credentials` | Report whether a tool has all required configuration. | `tools:write` |
    | `execute_tool` | Run an automation tool with the arguments you pass. See the warning below. | `tools:execute` |
    | `test_tool` | Run a tool against its live configuration and report the outcome. | `tools:execute` |
    | `create_script` | Create a script tool. It starts disabled with a skeleton code draft. | `tools:write` |
    | `get_script_draft` | Read a script tool's draft code, analysis, and diagnostics. | `tools:read` |
    | `update_script_draft` | Save a script tool's draft code. Risotto analyzes every save. | `tools:write` |
    | `test_script` | Run a script tool's draft code as a test execution. | `tools:execute` |
    | `get_script_run` | Read one script run's outcome and per-step trace. | `tools:read` |
    | `get_last_script_test_run` | Read the most recent test run for a script tool. | `tools:read` |
    | `publish_script` | Publish a script tool's draft as the live version. | `tools:write` |
    | `list_credentials` | List the names and types of the credentials in the vault. Never the values. | `tools:read` |
    | `request_vault_credential` | Ask for a new vault credential on a secure card. | `tools:write` |
  </Accordion>

  <Accordion title="Custom API sources and templates (22 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `list_custom_api_sources` | List the custom API sources (third-party REST integrations). | `custom_api_sources:read` |
    | `get_custom_api_source` | Inspect one source and its staged endpoint drafts. | `custom_api_sources:read` |
    | `find_api_spec_candidates` | Find a vendor's published API definition file on the web. | `custom_api_sources:read` |
    | `list_custom_api_templates` | List the vendor APIs Risotto ships a pinned specification for. | `custom_api_sources:read` |
    | `get_custom_api_template` | Inspect one template: its tag groups and endpoints. | `custom_api_sources:read` |
    | `search_custom_api_endpoints` | Search every shipped API specification for endpoints that match a description. | `custom_api_sources:read` |
    | `record_excluded_capability_request` | Record that you asked for an area that a template leaves out. | `custom_api_sources:read` |
    | `create_custom_api_source` | Create a custom API source. | `custom_api_sources:write` |
    | `create_custom_api_source_from_template` | Create a source from a template with all endpoints drafted. | `custom_api_sources:write` |
    | `update_custom_api_source` | Update a source's non-secret configuration. | `custom_api_sources:write` |
    | `ingest_openapi_spec` | Fetch an API definition by URL and stage every operation as a draft. | `custom_api_sources:write` |
    | `ingest_openapi_spec_content` | Stage every operation from a pasted API definition. | `custom_api_sources:write` |
    | `ingest_attached_file` | Stage operations from a file attached in the dashboard Assistant. | `custom_api_sources:write` |
    | `ingest_confirmed_web_spec` | Ground a source on a specification file found on the web. | `custom_api_sources:write` |
    | `stage_custom_api_drafts` | Stage hand-authored endpoint drafts on a source. | `custom_api_sources:write` |
    | `import_curl_endpoint` | Stage an endpoint draft parsed from a curl command. | `custom_api_sources:write` |
    | `discard_custom_api_draft` | Remove a staged endpoint draft. | `custom_api_sources:write` |
    | `test_custom_api_draft` | Run a staged draft against the real API before promotion. | `custom_api_sources:write` |
    | `validate_custom_api_draft` | Validate a staged read (GET) draft with one live test call. | `custom_api_sources:write` |
    | `promote_custom_api_drafts` | Promote staged read (GET) drafts into callable tools. | `custom_api_sources:write` |
    | `construct_custom_api_write_tool` | Turn a staged write draft into a disabled draft tool. | `custom_api_sources:write` |
    | `request_custom_api_credentials` | Report whether a source has its credentials. | `custom_api_sources:write` |
  </Accordion>

  <Accordion title="External MCP servers (8 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `list_external_mcp_servers` | List the connected external MCP servers. | `external_mcp_servers:read` |
    | `get_external_mcp_server` | Inspect one server: its tool catalog, drift, and imported tools. | `external_mcp_servers:read` |
    | `create_external_mcp_server` | Connect a third-party MCP server and discover its tool catalog. | `external_mcp_servers:write` |
    | `request_external_mcp_credentials` | Report whether a server has its bearer token. | `external_mcp_servers:write` |
    | `request_external_mcp_authorization` | Report whether a server's OAuth 2.1 authorization is complete. | `external_mcp_servers:write` |
    | `refresh_external_mcp_server` | Fetch a server's remote tool catalog again. | `external_mcp_servers:write` |
    | `import_external_mcp_tools` | Import chosen remote tools as automation tools. | `external_mcp_servers:write` |
    | `test_external_mcp_tool` | Call a remote tool on the live server before you import it. | `external_mcp_servers:write` |
  </Accordion>

  <Accordion title="Access management (8 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `list_applications` | List the applications that requestors can ask access to. | `applications:read` |
    | `list_access_rules` | List access rules with their state, application, limits, and approval. | `access_rules:read` |
    | `get_access_rule` | Get one access rule's full configuration. | `access_rules:read` |
    | `get_access_rule_authoring_guide` | Get the access-rule authoring guide as Markdown. | `access_rules:write` |
    | `create_applications` | Create up to 100 applications in one call. | `access_rules:write` |
    | `update_application` | Update an application's name, owner email, or keywords. | `access_rules:write` |
    | `create_access_rules` | Create up to 100 access rules in one call. New rules start disabled. | `access_rules:write` |
    | `update_access_rule` | Update one access rule. Omitted fields keep their value. | `access_rules:write` |
  </Accordion>

  <Accordion title="Organization settings, request sources, and identity provider (11 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `get_org_settings` | Read agent instructions, approval timers, auto-resolve days, and the notifications channel. | `settings:read` |
    | `update_org_setting` | Set one organization setting. | `settings:write` |
    | `find_slack_channels` | Find Slack channels by name. Returns IDs for the channel tools. | `settings:read` |
    | `set_slack_notifications_channel` | Set the Slack channel where Risotto posts admin notifications. | `settings:write` |
    | `list_request_sources` | List every request source with its routing department and settings. | `settings:read` |
    | `update_slack_channel_routing` | Update how a Slack channel routes requests. | `settings:write` |
    | `update_msteams_channel_routing` | Update how a Microsoft Teams channel routes requests. | `settings:write` |
    | `update_support_email_address` | Update the settings of a support email address. | `settings:write` |
    | `get_idp_configuration` | Read how the identity provider is configured. | `settings:read` |
    | `get_vendor_tenant_hosts` | Read the vendor site that each connection stores, such as your Atlassian site. | `settings:read` |
    | `request_okta_credentials` | Report whether the Okta connection is configured. | `settings:write` |
  </Accordion>

  <Accordion title="Artifacts and audit log (6 tools)">
    | Tool | What it does | Scope |
    | - | - | - |
    | `list_artifacts` | List the artifact pages (dynamic dashboards) with their URLs. | `artifacts:read` |
    | `get_artifact` | Get one artifact page, including its HTML. | `artifacts:read` |
    | `list_artifact_tools` | List the tools an artifact page can call. | `artifacts:read` |
    | `delete_artifact` | Delete an artifact page. Its audit log is kept. | `artifacts:write` |
    | `list_audit_events` | List configuration-change audit events. | `audit:read` |
    | `get_audit_event` | Get one audit event with its field-level diff. | `audit:read` |
  </Accordion>
</AccordionGroup>

<Warning>
  Grant `tools:execute` only to a user who may approve every tool it can reach.
  `execute_tool` runs the tool at once, also when the tool's approval setting is
  **Required** in the dashboard. Risotto records the call against the user who
  authorized the OAuth client.
</Warning>

<Note>
  Six tools collect secrets on a secure card in the dashboard Assistant:
  `request_tool_credentials`, `request_custom_api_credentials`,
  `request_external_mcp_credentials`, `request_external_mcp_authorization`,
  `request_okta_credentials`, and `request_vault_credential`. From an external
  MCP client they only report the current state. Enter the secret in the
  dashboard instead. `ingest_attached_file` reads a file uploaded in the
  dashboard Assistant and has no use from an external client.
</Note>

The set of tools grows as Risotto adds capabilities. Call `tools/list` against your endpoint to see the current list of tools that your scopes allow, with input schemas.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The bearer token is missing, malformed, expired, or revoked.

    * The client should refresh its token automatically. If it doesn't, remove and re-add the MCP server in the client to trigger a fresh consent flow.
    * If you configured the server with a Risotto API key instead of signing in, the response says so. Remove the key from the client's configuration and reconnect; the client prompts you to sign in with OAuth.
    * The `WWW-Authenticate` response header points to the OAuth discovery document — most clients use this automatically to recover. If you're building a custom client, follow that pointer.
  </Accordion>

  <Accordion title="403 insufficient_scope or access_denied">
    You are no longer in the organization, or none of the requested scopes is one that your role can hold.

    * A user who is not in the organization gets `403` with `insufficient_scope` ("Only org admins, managers, and members can use Risotto MCP.").
    * At consent, a Member whose client requests only scopes outside the [Member scopes](#scopes-and-organization-roles) goes back to the client with `access_denied`.
    * A `503` with `Retry-After: 30` means that Risotto could not read your role. Try again.
  </Accordion>

  <Accordion title="Consent screen redirects fail or loops">
    Risotto's Dynamic Client Registration follows [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) for **native/desktop clients**: they register either a `localhost` loopback redirect URI or a private-use URI scheme (like `cursor://`). Claude Desktop and the MCP Inspector use loopback; Cursor uses its `cursor://` scheme, and a single registration can mix native and web redirect URIs.

    Hosted clients like ChatGPT are different — they register their own public HTTPS redirect URI, which Risotto's DCR accepts. If you're building a custom **desktop** client, use a loopback or private-use-scheme redirect. If you're building a custom **hosted/web** client and registration is failing, double-check the redirect URI is a valid HTTPS URL your service controls.
  </Accordion>

  <Accordion title="Tool call returns a missing scope error">
    Scope failures come back as a successful JSON-RPC response whose `result.isError` is `true`, with a message naming the missing scope (for example, `tickets:read`).

    Revoke the client in the dashboard and reconnect — the consent screen lets you approve the additional scope. A Member cannot approve a scope outside the [Member scopes](#scopes-and-organization-roles). Ask an Org Admin for the Admin or Manager role.
  </Accordion>

  <Accordion title="429 Too Many Requests">
    You've hit Risotto's rate limit. `/mcp` requests are throttled per credential at 1,000 requests per hour by default, and OAuth token issuance is throttled per client.

    The response includes `Retry-After` and `X-RateLimit-*` headers showing the reset window. Back off until the window resets, or contact support if you consistently need higher limits.
  </Accordion>

  <Accordion title="Tools don't appear in the client">
    * Restart the client after editing its config file — most clients only read MCP config at startup.
    * Run the `curl` snippet above to confirm the endpoint is reachable.
    * `tools/list` returns only the tools that the credential's scopes allow. If a tool you expect is missing, check the scopes you granted, and for OAuth, check your organization role. See [Scopes and organization roles](#scopes-and-organization-roles).
  </Accordion>
</AccordionGroup>