Connecting Okta as an HRIS Integration

Last updated: May 1, 2026

Span supports Okta as an HRIS data source, syncing your employee directory and organizational structure—including reporting relationships, departments, and job metadata—to keep your people data current in Span.

Prerequisites

Before connecting, make sure you have:

  • Span Organization Admin access

  • An Okta Admin account with permission to generate API tokens

  • Your Okta tenant domain (e.g., your-org from your-org.okta.com)

Step 1: Generate an Okta API Token

  1. Log in to your Okta Admin Dashboard

  2. Navigate to Security → API → Tokens

  3. Click Create Token and give it a descriptive name (e.g., Span HRIS Integration)

  4. Copy the token value — you won't be able to see it again

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

Step 2: Connect Okta in Span

  1. In Span, go to Settings → Integrations

  2. Find and click the Okta (HRIS) tile

  3. Enter your Okta Tenant — this is just the subdomain portion (e.g., if your Okta URL is acme.okta.com, enter acme)

  4. Paste your API Token

  5. Click Connect — Span will verify the credentials before saving

Step 3: Wait for Initial Data Load

After connecting, Span will begin loading your Okta data. This takes approximately 10 minutes. You'll see a confirmation message:

"Connection established! You'll be able to configure your sync in 10 minutes."

You cannot configure what to sync until this initial load is complete.

Step 4: Configure What to Sync

Once the data load is complete, a configuration dialog will open. You'll need to:

  1. Select at least one department using the hierarchical selector — this field is required. Use it to choose the specific parts of your org to sync into Span

  2. People data — always synced (pre-checked, cannot be disabled)

  3. Team data — optionally sync Okta groups as teams in Span (off by default)

Click Finish to save your configuration.

What Gets Synced from Okta

Span uses the following data from your Okta directory. The table below maps each Span field to the corresponding Okta profile attribute that must be populated for the sync to work correctly.

People Data

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 / grade

Custom attribute (e.g., profile.jobLevel)

Optional

Termination date

Derived from user status (DEPROVISIONED)

Optional

GitHub / GitLab username

Custom attribute (e.g., profile.githubUsername)

Recommended

Profile photo

profile.profileUrl or Okta-hosted avatar

Optional

Custom attributes: Job level and VCS usernames (GitHub/GitLab) require custom profile attributes in Okta. If these aren't populated in your directory, those fields will be blank in Span.

Team / Department Data

Span Field

Okta Source

Team name

Okta Group name

Parent team

Okta Group's parent group (if hierarchical groups are configured)

Team membership

User's group memberships in Okta

Ensure Your Okta Directory Is Set Up Correctly

For the best results before connecting, verify that the following are populated for all active users in Okta:

  • profile.firstName and profile.lastName

  • profile.email (work email)

  • profile.manager or profile.managerId (for org hierarchy)

  • profile.title (job title)

  • profile.startDate (hire date)

  • Group memberships are assigned and reflect your actual org structure

For job level and VCS usernames, create custom user profile attributes in Okta Admin → Directory → Profile Editor and populate them for your users before syncing.

Troubleshooting

Issue

Resolution

"Invalid credentials" on connect

Double-check the tenant domain (no .okta.com suffix) and verify the API token hasn't expired

Configuration dialog doesn't appear after connecting

The initial data load (~10 min) may not be complete yet. Wait and return to Settings → Integrations → Okta (HRIS)

Missing employees after sync

Check that the API token has read access to all users, and confirm your department selection includes the right groups

Org hierarchy not reflecting correctly

Ensure profile.manager or profile.managerId is populated for all users in Okta

Job level or VCS usernames not syncing

Confirm that custom Okta profile attributes exist and are populated for your users

"Please select at least one team" error

The Departments field requires at least one selection — you cannot sync all departments by leaving it blank

Disconnecting Okta

To remove the integration, go to Settings → Integrations → Okta (HRIS) and click Disconnect. This will stop all future syncs. Previously synced data will remain in Span until manually removed.