OKTA002 - Okta Authorization Failed

Agent error code #OKTA002 indicates that the Okta API authenticated the agent's token but rejected the network-zone request with HTTP 403 Forbidden. The admin role behind the token lacks the permissions required to read or update network zones.

This error is distinct from authentication failures (#OKTA001), which occur when the token itself is rejected. Error #OKTA002 means the token is valid but its admin role is too narrow.

Common causes include:

• The token belongs to an admin with a read-only role (e.g. Read-only Administrator) that cannot update network zones
• The token belongs to a custom admin role that does not include the Manage IP Zones permission
• The admin user was downgraded after the token was issued

Steps to Resolve

Confirm the Admin Role

1. In the Okta admin console, navigate to Directory > People and open the service-admin user the API token belongs to
2. Click Admin roles in the user's profile
3. Confirm one of the roles listed has authority over network zones. The standard role with sufficient privileges is Super Administrator

For least-privilege deployments, create a custom admin role with only View groups and their details, Manage IP zones, and the relevant resource set covering the target Network Zone. See the Okta setup guide for the canonical custom-role definition.

Apply the Custom Role to a Resource Set

1. In Security > Administrators > Admins, find the Knocknoc service-admin user
2. Edit their assignment so the custom role is applied to a resource set that includes the target IP zone
3. Save and re-try the operation in Knocknoc

Regenerate the API Token After a Role Change

Okta caches role information on the token. After changing the admin's role, rotate the token (see OKTA001 for the steps) so the new role takes effect immediately.

Still Having Issues?

We can help you out, contact us at support@knocknoc.io.