Skip to main content
Version: 2026.09

Onboard your tenant

People cannot run jobs on the Istari Digital Platform until they belong to a tenant and have been granted tool access, and until the tenant has a connected agent with the integrations they need. User tutorials such as Web app 101 assume that work is done.

In this tutorial you set up a tenant for a pilot team, then confirm that a member without an administrator role can run @istari:extract on a spreadsheet.

By the end you will have:

  • A tenant with members, added one at a time and from a CSV file
  • A Tenant Administrator for the tenant
  • An agent connected to the tenant
  • Tool access granted for the integration the tutorials use
  • A verified extraction job run by a member without an administrator role

Time: about 30 minutes, plus the time IT needs to add a new tenant's people and to start the agent.

This tutorial describes installations with tenant management. If Settings has a Password entry, your installation does not use tenant management; follow On installations without tenant management instead.

Prerequisites​

  • An administrator role. To create a tenant you need the Platform Administrator role. A Tenant Administrator onboards their existing tenant instead. See Administrators for what each role can do. If nobody on the installation holds an administrator role yet, your IT administrator creates the first Platform Administrator.
  • IT help. For a tenant you create in Step 2, your IT administrator adds its people. IT also installs the agent on a host with the Open Spreadsheet module, using the key generated in Step 7.
  • An account for each member. Each member signs in with an account in your sign-in provider. Its verified email address must match the one they are added with. Adding someone in Istari does not create this account. If someone has none, ask your IT administrator to create one; see Creating New Users. On Microsoft Entra ID, IT also needs each member's Entra Object ID, because Entra does not match people by email.
  • Your pilot team:
    • A tutorial user: a colleague who will hold no administrator role. You verify job execution as this person in the last step.
    • A pilot lead to become the tenant's Tenant Administrator. If you are a Tenant Administrator onboarding your own tenant, this can be you. A Platform Administrator who already belongs to a tenant cannot be the pilot lead of a new one, because a person belongs to at most one tenant.
    • A CSV file listing the rest of the team, with an email column and optionally first_name and last_name. See File format.

Download the sample spreadsheet used in Web app 101; your tutorial user needs it in the last step:

Step 1 — Confirm your administrator role​

  1. Sign in to the Istari Digital web app.
  2. Click your avatar at the bottom of the sidebar, then Settings, and check that the Settings navigation has an Admin group. It appears only for administrators.
  3. If you are a Platform Administrator, confirm that the avatar menu also offers Platform Admin Console.

If the Admin group is missing, ask an administrator to grant you a role. If nobody holds one yet, see the prerequisites.

Step 2 — Create the tenant​

Platform Administrators only. A Tenant Administrator onboards their existing tenant and continues at Step 3.

  1. Click your avatar, then Platform Admin Console. The Tenants page opens.
  2. If your team already has a tenant, use it instead of creating one and skip to Step 3. If it is on the Suspended tab, reactivate it first.
  3. Click New tenant.
  4. Enter a Display name and a Slug. The slug takes lowercase letters and numbers, with single hyphens between them, up to 63 characters. It cannot change later.
  5. Click Create tenant.
  6. Ask your IT administrator to add the tenant's people, and give them its slug. IT follows Adding people to a tenant.

For now, the web app cannot add people to a tenant created here. Skip Steps 3 and 4: give IT the emails of your tutorial user, your pilot lead and the rest of the team (your CSV file) to add, then continue at Step 5 once they appear in the tenant's Members section as Pre-registered.

See Tenants for editing, the default tenant, and suspension.

Step 3 — Add your tutorial user​

For a tenant you created in Step 2, IT adds people instead; skip to Step 5.

You cannot add someone who already belongs to another tenant.

  1. Open the list of people in the tenant:
    • As a Platform Administrator, on the Platform Admin Console's Tenants page, click the new tenant's name and use its Members section.
    • As a Tenant Administrator, open Settings > Admin > Users. People you add join your tenant.
  2. Click Add user.
  3. Enter the tutorial user's Email, First Name and Last Name.
  4. Click Add user in the dialog.

The tutorial user appears under Pre-registered until they first sign in.

Add your pilot lead the same way. Skip this only if you are the pilot lead and already belong to the tenant.

See Add a person.

Step 4 — Pre-register the rest of the team from a CSV file​

  1. In the same list, click Add from CSV.
  2. Click Choose CSV file and pick your file.
  3. Check the preview. It lists rows that will be skipped, such as an invalid or repeated email address, with the reason.
  4. Click Pre-register N people, where N is the number of rows to import.
  5. When the run finishes, review each row's outcome and click Close.

Importing the same file again is safe; rows already done come back as Already a member.

See Pre-register people from a CSV file for the file format, limits, and outcomes.

Step 5 — Make the pilot lead a Tenant Administrator​

  1. In the same list, find the pilot lead's row.
  2. Open the row's ⋮ menu and choose Make tenant admin.
  3. Read the confirmation and click Grant.

The pilot lead can now manage the tenant's people and agents. Do not grant an administrator role to the tutorial user; the last step checks that a member without one can run jobs.

See Grant an administrator role.

Step 6 — Have members sign in​

Ask the tutorial user and the pilot lead to sign in. In the list of people, watch them move from the Pre-registered tab to Active.

Tool access, control tags, and keys become available for a person only after they first sign in.

If someone sees You don't have access to Istari yet, see When someone cannot sign in.

Step 7 — Connect an agent to the tenant​

An agent runs jobs only for its own tenant. Generating a key creates the agent in the tenant of the administrator who generates it. So this step must be done by an administrator who belongs to the new tenant: the pilot lead, or you if you belong to it. If you do not, ask the pilot lead to do it.

  1. Signed in as that administrator, click Agents in the main sidebar.
  2. Click Generate Key.
  3. In the New Agent Access Key dialog, optionally enter a name in Agent name (optional), and click Generate.
  4. Click Download credentials. The key is shown only once.
  5. Send the file securely to IT for agent configuration.

The agent appears on All Agents once IT starts it, and Open Spreadsheet then appears under its installed modules.

If IT has shell access to the agent host, they can instead create and configure the agent there with the Istari CLI command stari key create-agent --configure, so the private key never leaves the host.

See Generate an agent key.

Step 8 — Grant tool access​

People can run functions only for tools you grant them.

  1. In the list of people, click Edit user (pencil) on the tutorial user's row.
  2. Open the Tool access tab.
  3. Search for Open Spreadsheet with Add tool and pick it. A new tool starts with every function selected.
  4. Clear any functions the team does not need. Keep @istari:extract.
  5. Click Save.

Repeat for each member who will run jobs in the pilot.

See Manage tool access for a user.

Step 9 — Verify job execution as your tutorial user​

Sign in as the tutorial user, not as an administrator, and run one extraction. This is the same check Web app 101 depends on.

  1. Click Resources in the sidebar.
  2. Upload Group3-UAS-Requirements.xlsx.
  3. Open the file and click Create Job.
  4. Select open_spreadsheet → @istari:extract.
  5. Click Execute Function.
  6. Wait until the job status is Completed.

If the job Failed:

  • Sign in as an administrator of the tenant and open Agents → All Agents. Confirm an agent has a green status badge, such as Idle, and lists Open Spreadsheet under Installed Modules. An agent in another tenant does not run this tenant's jobs.
  • On the tutorial user's Tool access tab, confirm Open Spreadsheet is granted with @istari:extract selected.

What you set up​

PieceWhy it matters
Tenant and membersEach person belongs to one tenant and signs in with their own account rather than a shared login.
Tenant AdministratorThe pilot lead can add people and manage agents without a Platform Administrator.
Connected agentJobs run on an agent in the same tenant; IT installs and starts it.
Tool accessEven with an agent, people cannot run functions you have not granted.
Verified extractProves the full path works before the team opens Web app 101.

What's next​

On installations without tenant management​

If Settings has a Password entry, your installation does not use tenant management. There are no tenants, no Platform Admin Console, and no Platform Administrators or Tenant Administrators to set up. Follow these steps instead of Steps 1 to 8.

You need:

  • administrator access, which your IT administrator grants in your sign-in provider;
  • IT available to start an agent with the Open Spreadsheet module;
  • a tutorial user;
  • the sample spreadsheet above.
  1. Confirm admin access. Click your avatar, then Settings, and check for an Admin group in the Settings navigation. If it is missing, ask your IT administrator to grant you administrator access.
  2. Connect an agent. If the top-right button on Agents reads Generate Token, follow Generate an agent token instead. Otherwise:
    1. On Agents, click Generate Key.
    2. Download the credentials and send the file securely to IT.
    3. The agent appears on All Agents once IT starts it.
  3. Add users.
    1. Open Settings > Admin > Users and pick your organization in the dropdown.
    2. Click Add user, enter Email, First Name and Last Name, and click Invite.
    3. New users appear under Invited until they accept and sign in, then move to Active.
  4. Grant tool access. Once the tutorial user is Active, click ⋯ on their row, then Manage Tool Access. Expand Open Spreadsheet, enable @istari:extract, and click Save.
  5. Verify job execution as in Step 9.

See On installations without tenant management in User Management for the rest of the Users page.