OKTA001 - Okta Authentication Failed

Agent error code #OKTA001 indicates that the Okta API rejected the API token in the agent's Authorization: SSWS <token> header. Okta returned HTTP 401 Unauthorized.

This error is distinct from authorization failures (#OKTA002), which occur when the token is valid but the admin role behind it lacks the required permissions. Error #OKTA001 means the token itself was not accepted.

Common causes include:

• The API token in the Knocknoc backend has a typo or trailing whitespace
• The token was rotated or revoked in Okta and the Knocknoc backend was not updated
• The token has expired. Okta API tokens expire after 30 days of inactivity by default
• The admin user the token belongs to has been deactivated or deleted
• The token was created against a different Okta org (preview vs production)

Steps to Resolve

Verify the API Token in Knocknoc

1. In the Knocknoc admin interface, open the backend configuration for the affected Okta Knoc
2. Re-enter the API Token from Okta. The value starts after SSWS is stripped, i.e. only the opaque token itself
3. Save and wait for the next grant operation

For the full setup, see the Okta setup guide.

Confirm the Token Exists in Okta

1. In the Okta admin console, navigate to Security > API > Tokens
2. Confirm an active token belonging to the Knocknoc service-admin user is listed
3. Note the Expires column. Tokens not used for 30 days are auto-revoked

Rotate the API Token

If the existing token cannot be verified or has expired:

1. In the same Tokens view, click Create token
2. Give it a name and copy the token value immediately. Okta only shows it once
3. Update the API Token field in the Knocknoc backend configuration
4. Revoke the old token once the new one is confirmed working

Still Having Issues?

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