Install & Compatibility
Where this runs
tested against v3.4.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 10.722s · 100.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 10.3s · import 9.922s · 103MB
106MB installed
● package 106MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from okta.client import Client
✗ from okta.OktaClient import OktaClient
The main client class is `Client` and is imported from `okta.client`.
Initialize the Okta client using environment variables for sensitive configuration and perform a basic API call to list users. This example demonstrates configuring the client with an API token for basic authentication. For OAuth 2.0 or private key authentication, the configuration dictionary would differ.
import os
from okta.client import Client as OktaClient
# Configure the Okta client using environment variables
# OKTA_ORG_URL should be your Okta tenant URL, e.g., https://your-org.okta.com
# OKTA_TOKEN should be an API Token with sufficient permissions (e.g., Read only administrator)
config = {
'orgUrl': os.environ.get('OKTA_ORG_URL', ''),
'token': os.environ.get('OKTA_TOKEN', ''),
'rateLimit': {
'maxRetries': 5
}
}
# Initialize the Okta client
okta_client = OktaClient(config)
# Example: List users
try:
# list_users() returns (users_list, response_object, error)
users, response, err = okta_client.list_users()
if err:
print(f"Error listing users: {err}")
elif users:
print(f"Successfully retrieved {len(users)} users. Showing first 3:")
for i, user in enumerate(users[:3]):
print(f"- User ID: {user.id}, Login: {user.profile.login}")
else:
print("No users found or empty response.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
# To run this example, set the following environment variables:
# export OKTA_ORG_URL="https://your-okta-domain.okta.com"
# export OKTA_TOKEN="your_okta_api_token"
Debug
Known issues
breakingVersion 3.0.0 introduced significant breaking changes by upgrading the SDK to OpenAPI Specification (OAS3.0). This may affect method signatures, request/response object structures, and API endpoint availability compared to 2.x.x versions.fixReview the official Okta Python SDK migration guide and updated documentation for 3.x.x to adapt your code to the new API structures and endpoints.
affects: >=3.0.0 (when migrating from <3.0.0)
breakingVersions 3.0.0 and 3.1.0 contain a critical bug that causes malformed requests for OAuth access tokens, preventing successful authentication via OAuth 2.0 client credentials or other OAuth flows.fixUpgrade to version 3.2.0 or later to resolve the OAuth access token request issue and ensure proper authentication via OAuth 2.0.
affects: 3.0.0, 3.1.0
gotchaPrior to version 2.9.9, the `client_assertion` JWT for client credentials flow was incorrectly placed in the URL query parameters instead of the request body, potentially causing authentication failures or security concerns.fixUpgrade to version 2.9.9 or later to ensure correct placement of `client_assertion` in the request body for client credentials authentication.
affects: <2.9.9
gotchaIn versions prior to 2.9.13, the SDK might not properly handle the expiration and renewal of OAuth 2.0 access tokens, potentially leading to errors when tokens expire during long-running operations.fixUpgrade to version 2.9.13 or later to benefit from improved OAuth 2.0 token management, including automatic expiration and renewal.
affects: <2.9.13
gotchaPrior to version 3.3.0, the SDK might fail to deserialize or gracefully handle Application objects with unknown `signOnMode` values, leading to errors when retrieving application data if new modes are introduced by Okta.fixUpgrade to version 3.3.0 or later to ensure robust handling of unknown `signOnMode` values in Application objects, preventing deserialization errors.
affects: <3.3.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'okta'
The `okta` Python package has not been installed in the current Python environment.
fixRun `pip install okta` to install the SDK.
ImportError: cannot import name 'UsersClient' from 'okta.client'
The client class structure in the `okta-sdk-python` library changed in newer versions (post-0.0.4 or around v1.x to v3.x transition). Specific resource clients like `UsersClient` are no longer directly imported; instead, a generic `Client` class is used to access different resources.
fixImport the main `Client` class as `OktaClient` and access resource methods through its instance, e.g., `from okta.client import Client as OktaClient` and then `okta_client.users.list_users()`.
OktaAPIError: HTTP 401 Unauthorized
The API client was initialized with an incorrect, expired, or revoked API token, or the `orgUrl` provided is invalid, preventing successful authentication with the Okta organization.
fixVerify that the `orgUrl` in your client configuration is correct (e.g., `https://{yourOktaDomain}`). Ensure the API token is valid, has the necessary permissions for the operation, and belongs to the specified Okta organization. AttributeError: 'OktaAPIException' object has no attribute 'errorCode'
When an `OktaAPIException` is caught, its detailed error information (like `errorCode` or `errorSummary`) is typically stored within its `args` attribute as a dictionary, rather than directly as attributes of the exception object itself.
fixAccess the error details by indexing the `args` attribute, for example, `err.args[0]['errorCode']` or `err.args[0]['errorSummary']` after catching `OktaAPIException as err`.
Upgrade
Version history
3.4.4latest on PyPI · released Jul 1, 2026
Audit
Dependencies
okta-jwt-verifierrequiredUsed internally by the SDK for JWT-related operations and token validation.
requestsrequiredUsed for making HTTP requests to the Okta API.
pyjwtrequiredUsed for JSON Web Token (JWT) handling.
python-joserequiredProvides JOSE (JSON Object Signing and Encryption) capabilities, particularly for cryptographic operations with JWTs.