Documented steps

Authenticate with scope okta.apps.manage.
Decide the client shape before creating. application_type: 'web' for confidential server-side apps, 'browser' for SPAs, 'native' for mobile/desktop, 'service' for machine-to-machine. token_endpoint_auth_method: 'client_secret_basic' or 'client_secret_post' for confidential apps, 'none' for public clients using PKCE, 'private_key_jwt' for OAuth-for-Okta service apps. grant_types: authorization_code, implicit, refresh_token, client_credentials.
POST /api/v1/apps with Content-Type: application/json and body {"name":"oidc_client","label":"My App","signOnMode":"OPENID_CONNECT","credentials":{"oauthClient":{"token_endpoint_auth_method":"client_secret_basic"}},"settings":{"oauthClient":{"redirect_uris":["https://example.com/oauth2/callback"],"response_types":["code"],"grant_types":["authorization_code","refresh_token"],"application_type":"web","consent_method":"REQUIRED"}}}. Omit client_id and client_secret so Okta generates them.
Capture credentials.oauthClient.client_id and, for secret-based auth methods, client_secret from the response immediately.
Confirm with GET /api/v1/apps/{appId} that status is ACTIVE and settings.oauthClient matches what you requested.
To rotate, add a second secret in parallel: POST /api/v1/apps/{appId}/credentials/secrets. The new secret is returned while the original remains Active and keeps working.
Deploy the new secret to every consuming client and verify the integration end to end before touching the old secret.
Deactivate the old secret: POST /api/v1/apps/{appId}/credentials/secrets/{secretId}/lifecycle/deactivate. Requests using it begin failing once its status is Inactive - this is your rollback point, since you can reactivate if something breaks.
Delete the old secret once you are confident it is unused: DELETE /api/v1/apps/{appId}/credentials/secrets/{secretId}.
Confirm the final state with GET /api/v1/apps/{appId}/credentials/secrets and verify only the intended secret is Active.
Official docs consulted: https://developer.okta.com/docs/guides/client-secret-rotation-key/main/ | https://developer.okta.com/docs/guides/implement-oauth-for-okta/create-oauth-app/ | https://developer.okta.com/docs/guides/implement-oauth-for-okta-serviceapp/main/ | https://developer.okta.com/docs/api/oauth2/

Known gotchas

An app can hold a maximum of two client secrets at once - you must deactivate and delete an old one before adding a third, so a stalled rotation blocks the next one.
Rotation is not atomic: generating a new secret does not disable the old one. Both work in parallel until you explicitly deactivate the old secret, which is what makes zero-downtime rotation possible but also means a forgotten cleanup leaves a live orphaned credential.
application_type constrains which grant_types and token_endpoint_auth_method values are valid; an inconsistent combination (for example a public native app with client_secret_basic) is rejected at creation.
OAuth-for-Okta service apps used for Management API access must use private_key_jwt and are locked to the client_credentials grant - this is not user-changeable.
Creating or modifying apps requires okta.apps.manage; a token scoped only to okta.apps.read returns 403 on POST /api/v1/apps.
If client_id and client_secret are omitted at creation Okta generates them from the app instance id - do not assume values are predictable or reproducible across environments in infrastructure-as-code.
The client_secret is returned in the creation and rotation responses; there is no later endpoint that redisplays an existing secret value, so capture it at the moment it is issued.

Create an OIDC application in Okta via the Apps API and rotate its client secret with zero downtime

Documented steps

Known gotchas

Related routes

Give your agent this knowledge — and 15,800+ more routes

Need this verified for your stack — or a route we don't have yet?