---
title: "Setting up Okta directory sync"
slug: "okta-1"
description: "Create an Okta API token and share it with Opensense, so your Okta users and groups sync to Opensense daily. Includes checking the sync and troubleshooting."
updated: 2026-01-29T00:38:57.000Z
canonical: "https://help.opensense.com/docs/okta-1"
---

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

# Setting up Okta directory sync

## Overview

Connect your Okta directory to Opensense, so your organization's users and groups sync automatically. Once it's set up, Opensense pulls directory data daily, to keep your email signature employee data up to date.

## Before you start

You need:

- **Super Admin access** in Okta (required to create API tokens)
- A way to share credentials securely with the Opensense implementation team

## Step-by-step guide


### Step 1: Go to the API token settings

1. Sign in to the **Okta Admin Console** as a Super Admin.
2. Go to **Security** > **API**.
3. Select the **Tokens** tab.

You see the API Tokens page, with a **Create token** button.

![The Okta Admin Console API page on the Tokens tab, with a Create token button](https://help.opensense.com/media/image-20-1-ef7281736fb1.png)

### Step 2: Create an API token

1. Select **Create token**.
2. Enter a name for the token (for example, "Opensense Directory Read").
3. For **API calls made with this token must originate from**, select **Any IP**.
4. Select **Create token**.

![The Okta Create token dialog, with a token name and Any IP selected](https://help.opensense.com/media/image-20-2-9101c64835bd.png)

A dialog shows "Token created successfully!", with your Token Value.

### Step 3: Copy and save the token

1. Select the **copy icon** next to the Token Value, to copy it.
2. Save the token in a secure location.
3. Select **OK, got it**.

![The Okta Token created successfully dialog, with the Token Value and its copy icon](https://help.opensense.com/media/image-20-6-fb577d225b17.png)

:::caution[You can only see the token once]
This is the only time you can view the token. After you select **OK, got it**, Okta stores the token as a hash, and you can't retrieve it. If you lose the token, you must create a new one.
:::

You now have the API token saved securely.

### Step 4: Get your Instance URL

Your Instance URL is your Okta domain. You can find it in your browser's address bar while you're signed in to the Admin Console. For example:

- `https://yourcompany.okta.com`
- `https://login.yourdomain.com`

You now have both the Instance URL and the API token saved.


### Step 5: Give the credentials to Opensense

Share this information securely with your Opensense implementation team:

<dl class="kb-insights-summary">
  <div><dt>Instance URL</dt><dd>Your Okta domain URL, for example <code>https://yourcompany.okta.com</code></dd></div>
  <div><dt>API Token</dt><dd>The token value you copied</dd></div>
</dl>

:::note[Share credentials securely]
Use a secure method to share credentials, such as a password manager or an encrypted communication channel.
:::


### Step 6: Check the connection

Once Opensense configures your credentials, check that the sync works:

1. In Opensense, select **Manage** in the navigation bar.
2. Select **Users**.
3. Select **Action** in the upper-right corner.
4. Select **Run Sync**.
5. Confirm that **Okta** appears as a source, and that the sync completes successfully.

Users and groups from Okta appear in Opensense. After the initial setup, the sync runs automatically once a day.

## Troubleshooting

<div class="kb-faq">
  <details id="invalid-token">
    <summary><span class="kb-faq__question">Invalid token</span></summary>
    <div class="kb-faq__answer">
      <p><strong>Cause:</strong> the API token was entered incorrectly, or was revoked, or has expired.</p>
      <ol>
        <li>In Okta, go to <strong>Security</strong> &gt; <strong>API</strong> &gt; <strong>Tokens</strong>.</li>
        <li>Check whether your token is in the list, and active.</li>
        <li>If the token is missing or inactive, create a new token, and share it with Opensense.</li>
      </ol>
      <p>API tokens are valid for 30 days, and renew automatically each time Opensense syncs. Because syncs run daily, tokens stay active. A token only expires if it isn't used for 30 or more days in a row.</p>
    </div>
  </details>
  <details id="access-denied">
    <summary><span class="kb-faq__question">Access denied</span></summary>
    <div class="kb-faq__answer">
      <p><strong>Cause:</strong> the token was created by an admin without enough permissions.</p>
      <ol>
        <li>Check that a <strong>Super Admin</strong> created the token.</li>
        <li>If not, have a Super Admin create a new token.</li>
        <li>Share the new token with Opensense.</li>
      </ol>
    </div>
  </details>
  <details id="sync-delays">
    <summary><span class="kb-faq__question">Sync delays</span></summary>
    <div class="kb-faq__answer">
      <p><strong>Cause:</strong> the automated sync runs once a day, so new users or groups may not appear right away.</p>
      <ol>
        <li>In Opensense, go to <strong>Manage</strong> &gt; <strong>Users</strong>.</li>
        <li>Select <strong>Action</strong> &gt; <strong>Run Sync</strong> to start a sync manually.</li>
        <li>If issues continue, contact Opensense Support.</li>
      </ol>
    </div>
  </details>
</div>

## Still having issues?

Contact Opensense Support at [help@opensense.com](mailto:help@opensense.com). Include:

- Screenshots of any error messages
- Your Instance URL (don't show your API token in screenshots)
- The steps you've already tried

## What's next

- [Running a directory sync manually](https://help.opensense.com/docs/forced-sync-from-a-directory)
- [Field data priority](https://help.opensense.com/docs/field-data-priority)