Connecting Okta as an HRIS Integration

Last updated: October 30, 2026

Span can use Okta as your HR data source. It syncs your employee directory, including reporting lines and job details, so your people data in Span stays current.

Why it matters

If Okta is where your organization keeps the most complete record of who works where, connecting it saves you from maintaining the roster in Span by hand. New hires, leavers, and manager changes flow into Span without manual edits.

Okta (HRIS) brings in people data. It doesn't control who can log in or what they can see. For login, set up SCIM or single sign-on separately. For access, assign permission groups in Span.

How it works

Span connects to Okta through Kombo, Span's HR integration partner. After you connect, Kombo loads your Okta directory, and you choose which departments to sync.

Two ways Okta data reaches Span. Span sets up one of these for your organization:

	HRIS sync	Directory Sync with Okta as a source
How changes land	Okta data is written to your people records directly	Each change is staged in Settings → Directory Sync for review
Review before changes	No	Yes, someone with Manage Directory Sync clicks Apply, unless Span turns on auto-apply
Team structure	From Okta groups, if Span turns on team sync	From Okta groups, the Span Sync API, or your Git provider's teams
Directory Sync settings page	Not shown	Shown

If you don't see Settings → Directory Sync, your organization uses HRIS sync. To move to Directory Sync, for example to review changes before they apply or to take your team structure from another source, contact your Span account team. See Using Directory Sync for Roster Management.

People data

The table maps each Span field to the Okta profile attribute that should be populated.

Span field	Okta profile attribute	Required?
First name	`profile.firstName`	Required
Last name	`profile.lastName`	Required
Email address	`profile.email`	Required
Start date	`profile.startDate` (or employment record)	Required
Manager (reports-to)	`profile.manager` or `profile.managerId`	Required
Job title	`profile.title`	Optional
Job level or grade	Custom attribute (for example `profile.jobLevel`)	Optional
Termination date	Derived from user status (`DEPROVISIONED`)	Optional
GitHub or GitLab username	Custom attribute (for example `profile.githubUsername`)	Recommended

Job level and Git usernames need custom profile attributes in Okta. If they aren't populated, those fields are blank in Span.

Team data

Okta groups can also sync as Span teams. Span turns this on for your organization, so ask your Span team if you want it.

Span field	Okta source
Team name	Okta group name
Parent team	The group's parent group, if you use hierarchical groups
Team membership	The user's group memberships in Okta

Setup

Before you start

In Span, you need the Manage Integrations permission. Owners, Admins, and Integration Admins have it.
In Okta, you need an admin account that can create API tokens.
Know your Okta tenant, the subdomain in your-org.okta.com.
Check that these are populated for all active users: first and last name, work email, manager, job title, start date, and group memberships that reflect your org. For job level and Git usernames, create custom attributes in Okta Admin → Directory → Profile Editor and fill them in.

Step 1: Create an Okta API token

Log in to the Okta Admin Dashboard.
Go to Security → API → Tokens.
Click Create Token and give it a clear name, such as Span HRIS Integration.
Copy the token. Okta won't show it again.

The token needs read access to your Okta users (/api/v1/users). A service account or dedicated admin user is recommended.

Step 2: Connect Okta in Span

In Span, go to Settings → Integrations and open Okta (HRIS).
Start the connection. A secure Kombo window opens.
Enter your Okta tenant (just the subdomain, for example acme for acme.okta.com) and paste the API token. The credentials are checked before they're saved.

Step 3: Wait for the first data load

Loading your Okta data takes about 10 minutes. Until it finishes, the integration shows a message that the connection is established and you can configure the sync once loading completes.

Step 4: Choose what to sync

Under Departments, select the parts of your organization to sync. You must pick at least one.
People data is always included and can't be turned off.
Click Save.
Tell your Span contact. Span reviews the data with you and sets up HRIS sync or Directory Sync before your roster starts changing.

Things to know

One HR system per organization: if you connect Okta as your HR source, you can't also connect Google Workspace or another HR system. Pick whichever holds the most complete people data.
Okta (HRIS) is separate from Okta SCIM and SSO: SCIM grants and revokes Span access for people who already exist in Span, and never creates people or sets teams or managers. SSO controls how people sign in. You can use all three together.
Department scope decides who comes in: people outside the departments you select aren't synced. Add a department to bring its people in.
Synced fields are read-only in Span: fields that come from Okta can't be edited in People Management. Change them in Okta.
CSV upload is off: Sync from CSV is disabled while HRIS sync or Directory Sync manages your roster.
New people and contributor status: when Span creates a person from Okta and your Okta data includes Git usernames, only people with a Git username are marked as code contributors. Without Git usernames, every new person is marked as a contributor. Check new hires who don't write code, such as managers outside engineering.
Email is the match key: Span matches people by email. With HRIS sync, if someone's email changes in Okta, Span creates a second record for them rather than updating the first. Contact support to merge the records.
Rehires: when a person's termination date is earlier than their start date, Span treats it as a past employment and keeps them active.
Self-managers are dropped: if Okta lists someone as their own manager, Span ignores that manager link.
Directory Sync checks before applying: with Directory Sync, Span won't apply a staged sync where anyone lacks a start date, or where a person's manager isn't in the synced departments. Fix the data in Okta, or ask Span to turn on the option that skips missing managers.
Worked example: you add a new engineering manager, Priya, to Okta in the Engineering department. With HRIS sync, she appears in Span once the next sync runs. With Directory Sync, she appears in a staged sync, and joins your roster when an admin clicks Apply. Either way, an admin then adds her to the right permission group in Span so she can see her team.

Troubleshooting

Issue	Resolution
"Invalid credentials" on connect	Check the tenant (no `.okta.com` suffix) and that the API token hasn't expired.
Configuration options don't appear after connecting	The first data load (about 10 minutes) may not be finished. Wait, then return to Settings → Integrations → Okta (HRIS).
"Please select at least one team" error	The Departments field needs at least one selection. You can't sync everything by leaving it blank.
Employees missing after sync	Check that the token can read all users and that your department selection includes them.
A new person can't see anything in Span	Okta brings in people data only. Add them to a permission group in Span, and make sure they can sign in (SSO or SCIM).
Directory Sync won't apply: missing start date	Populate `profile.startDate` in Okta for those people, then wait for the next sync.
Directory Sync won't apply: "Manager not found"	The person's manager isn't in the departments you selected. Add the manager's department, or ask Span about skipping missing managers.
Org hierarchy looks wrong	Make sure `profile.manager` or `profile.managerId` is populated for all users.
Job level or Git usernames not syncing	Confirm the custom profile attributes exist in Okta and are populated.
A person appears twice	Their email likely changed in Okta. Contact support to merge the records.

Disconnecting Okta

To disconnect Okta and stop syncing, contact your Span account team or support.

Using Directory Sync for Roster Management

People Data & Roster Management

Roles & Permissions in Span

Setting Up SCIM Provisioning for Span

Setting up SSO with Span

Need help?

Contact your Span account team or reach out to support@span.app.

INTERNAL: Before you publish (delete this section)

Leavers under HRIS sync: the HRIS write path (hris.command.service.ts → upsertSyncedPeople) only upserts and sets Terminated from the termination date. I found no sweep that terminates people who drop out of the Okta data. Confirm with eng whether anything downstream does, then decide whether to add a line.
"About 10 minutes" first load and the DEPROVISIONED → termination date mapping are Kombo-side and carried over from the old article; not verifiable in our code.
Can an org have both HRIS sync and Directory Sync on? The code treats them as separate settings (KomboDevIntegrationWrite vs DirectorySync). The article assumes one or the other.