Okta Directory

Antenna syncs your Okta directory to keep contributor identities, emails, employment details, and groups current. Use it to resolve Git, project tracker, and AI tool accounts to the same person without maintaining a manual user list.

This is an API Service integration and is separate from Antenna’s Okta Single Sign-On integration. SSO controls how users log in to Antenna; the Okta Directory integration reads your directory for identity resolution. You can use either one on its own, or both together.

Prerequisites

Okta administrator access to install and authorize applications from the Okta Integration Network (OIN)
Admin access to your Antenna organization

Required permissions

The integration requests two read-only scopes:

Scope	Purpose
`okta.users.read`	Read users and their profile attributes
`okta.groups.read`	Read groups and their memberships to create identity groups in Antenna

Setup

Install Antenna from the OIN

In the Okta Admin Console, go to Applications and Resources > API Service Integrations.
Click Add Integration.
Select Antenna, then click Next.

Antenna is an API service integration, so it is listed under Applications and Resources > API Service Integrations rather than in the app catalog. See Okta’s Add an API Service Integration guide for details.

Install and authorize

On the Authorize step, review the requested permissions — reading users’ profiles and reading groups and their members — and click Install & Authorize.

Copy your credentials

Okta opens the integration’s General tab with the Copy your client secret dialog already open.

Click Copy to clipboard and store the client secret somewhere safe, then close the dialog.
Under Client Credentials, copy the Okta Domain and Client ID.

The client secret appears only once. If you close the dialog without copying it, click Generate new secret under Client Secrets to create a new one.

Connect in Antenna

In app.antenna.dev , go to Settings > Sources, click Add source, and select Okta Directory.
Enter your Okta domain, Client ID, and client secret.
Click Connect.

Antenna validates the credentials when you connect, so an invalid secret or a missing scope is rejected immediately. After connecting, Antenna imports your directory and then refreshes it automatically.

Data collected

Antenna reads user records and their profile attributes, including name, email, username, status, and manager. We use these to match directory users to your Git, project tracker, and AI tool accounts. Antenna also reads Okta groups and their memberships to create groups that you can use to filter enterprise data.

Antenna only reads from Okta. We never create, update, deactivate, or delete Okta users or groups, and we do not write any data back to your directory.

Field mapping

Choose which Okta profile attributes fill each identity field in Antenna. Go to Settings > Sources, click Configure on Okta Directory, and use the Field Mapping card. Each row has:

Antenna field: the identity field the row fills.
Okta attribute: the Okta profile attribute copied into the field, or Don’t sync to leave the field alone.
Existing values: what happens when the field already has a value.
Example: what the saved mapping writes for one user from your directory.

Fields you can map

Antenna field	Default Okta attribute
Display Name	Don’t sync
Email	`email`
Role	`title`
Manager	Don’t sync
Team(s)	Don’t sync
Department	`department`
Company	`organization`
Employment Type	Don’t sync
Location	`city`, `state`, and `countryCode`, joined (for example, “London, England, GB”)
Product Line(s)	Don’t sync
Seniority	Don’t sync

The Okta attribute list includes every attribute Antenna has seen on your users’ Okta profiles, including custom attributes such as jobLevel. A new attribute appears after the next sync.

Team(s) and Product Line(s) split values on commas and semicolons, so Billing, Payments becomes two teams.
Manager expects an attribute that identifies the manager, such as managerId. Antenna matches the value to another Okta user by Okta user ID, username, email, or employee number, and sets the manager to that user’s Antenna identity. If the value matches no one, or matches more than one user, the current manager is kept.
The card picks one attribute per field. The default Location mapping is the only one that combines several attributes, and the card shows it as city. Saving the card keeps only the attribute selected.

Existing values

Option	Behavior
Only fill empty	Writes the field only when it is blank.
Update unless edited (default)	Fills blank fields and keeps values that came from Okta up to date. Values someone edited in Antenna are kept.
Always overwrite	Always writes the Okta value, replacing manual edits.

An empty Okta value never clears a field. If a user’s attribute is blank in Okta, the field keeps its current value in Antenna.

When changes apply

Clicking Save or Reset to defaults starts a sync right away. If a sync is already running, another one starts when it finishes. After that, the directory syncs automatically every 2 hours. Reset to defaults restores the mappings in the table above.

Rotate credentials

Rotate the client secret if it is lost or exposed:

In Okta, go to Applications and Resources > API Service Integrations and select the Antenna integration.
In the Client Secrets section of the General tab, click Generate new secret and copy it.
In Antenna, go to Settings > Sources and click Configure on Okta Directory. Click Update credentials, enter the new client secret, and click Update credentials to save it.
Once the sync succeeds, set the previous secret to Inactive in Okta and delete it.

Your Okta domain and client ID do not change when you rotate the secret.

Disconnect

In Antenna, go to Settings > Sources and click Configure on Okta Directory. Open the More actions (...) menu, click Disconnect, and confirm.
In Okta, go to Applications and Resources > API Service Integrations, select the Antenna integration, and click Revoke to remove the granted scopes.

Disconnecting stops all future syncs. Previously imported identities remain in Antenna so your historical metrics stay intact.

Troubleshooting

Issue	Resolution
Invalid credentials when connecting	Confirm the client ID and secret come from the same Antenna integration, and that the secret is still active in Okta.
Lost client secret	The secret is shown only once. Rotate the credential to generate a new one.
Insufficient scope errors	Reopen the integration under Applications and Resources > API Service Integrations in Okta and confirm both `okta.users.read` and `okta.groups.read` are granted. Re-run Install & Authorize if either scope is missing.
Users missing from Antenna	Deactivated and suspended users may be excluded. Confirm the user is active in Okta and wait for the next sync to complete.
Sync stopped unexpectedly	Verify the integration is still active in Okta and that the client secret has not been rotated or revoked.

Support

If you need help connecting or verifying your directory sync, contact us at support@antenna.dev.