Gateco connects to Okta using the Management API with SSWS token authentication. Once connected, Gateco runs Okta group sync every 60 minutes (configurable) and makes users and groups available as principals for identity-aware retrieval — enabling RAG access control policies based on your Okta workforce identity groups.
Okta integration requires the Growth plan or above.
Step 1 — Find your Okta domain
Your Okta domain is the hostname part of your Admin Console URL.
| If your Admin Console URL is... | Your Okta domain is... |
|---|---|
https://dev-12345.okta.com/admin | dev-12345.okta.com |
https://mycompany.okta.com/admin | mycompany.okta.com |
https://mycompany.oktapreview.com/admin | mycompany.oktapreview.com |
Pass only the hostname — no https:// prefix, no /admin suffix.
Step 2 — Create an API token
- In the Okta Admin Console, navigate to Security → API → Tokens.
- Click Create Token.
- Give it a name (e.g. gateco-sync).
- Copy the token value immediately — it is shown only once.
For least-privilege access, create the token using an account with the Read-only Administrator role. This restricts the token to read operations only.
Step 3 — Add credentials to Gateco
- In the Gateco dashboard, navigate to Identity Providers → Add provider → Okta.
- Enter your Okta domain and API token.
- Click Test connection. Gateco will display the number of users and groups found.
- Click Save.
| Field | Value |
|---|---|
Okta Domain | Your org hostname (e.g. dev-12345.okta.com) |
API Token | The SSWS token from Step 2 |
Step 4 — Trigger initial sync
After saving the provider, click Sync now. Gateco will:
- Fetch all active users via GET /api/v1/users.
- Fetch all groups via GET /api/v1/groups.
- Fetch group memberships for each group.
- Create or update Principal records.
Once synced, principals appear in the Principals list and are available for policy conditions.
How Gateco uses your Okta data
| Okta field | Gateco principal field | Use in policy conditions |
|---|---|---|
profile.email | email | principal.email |
profile.displayName | display_name | Display only |
profile.department | attributes.department | principal.attributes.department |
Group membership | groups array | principal.groups |
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
Authentication failed (401) | Invalid or expired API token | Regenerate the API token in Okta and update it in Gateco |
Zero users synced | Okta domain includes https:// prefix | Remove the https:// prefix and pass only the hostname |
Department attribute empty | Okta profile.department not set | Set the Department attribute on users in Okta Directory → People → user profile |