{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Client authentication methods","description":"Okta Developer API Reference","siteUrl":"https://developer-okta.login.adsbillinghub.com","keywords":"okta, api reference docs","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"client-authentication-methods","__idx":0},"children":["Client authentication methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some endpoints require client authentication. To make requests to these endpoints, you must include a header or parameter in the request depending on the authentication method that the application is configured with."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When registering an OAuth 2.0 client application, specify an authentication method by including the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/okta-oauth/oauth/client/replaceclient#client/replaceclient/t=request&path=token_endpoint_auth_method"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_endpoint_auth_method"]}]}," parameter."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," If you don't specify a method when registering your client, the default method is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_basic"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a client application and specify the authentication method, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/okta-oauth/oauth/client/createclient"},"children":["Create a Client application"]},". To change the client authentication method of an existing app, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/okta-oauth/oauth/client/replaceclient"},"children":["Replace a Client Application"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Okta supports the following authentication methods, detailed in the sections below:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_basic"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_post"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_jwt"]},": Use one of these methods when the client has a client secret. Public clients (such as single-page and mobile apps) that can't protect a client secret must use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none"]}," below."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["private_key_jwt"]},": Use this when you want maximum security. This method is more complex and requires a server, so it can't be used with public clients."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"x-lifecycle","attributes":{"className":"ea"},"children":[]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["self_signed_tls_client_auth"]},": Use this when you want to bind access tokens to a client TLS certificate. This method requires a server and isn't supported for public clients."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none"]}," - Use this with clients that don't have a client secret (such as applications that use the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developer-okta.login.adsbillinghub.com/docs/guides/implement-grant-type/authcodepkce/main/"},"children":["authorization code flow with PKCE"]}," or the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developer-okta.login.adsbillinghub.com/docs/guides/implement-grant-type/implicit/main/"},"children":["implicit flow"]},")."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"client-secret","__idx":1},"children":["Client secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your client's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_endpoint_auth_method"]}," is either ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_basic"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_post"]},", include the client secret in outgoing requests."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_basic"]},": Provide the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," values in the Authorization header as a Basic auth base64-encoded string with the POST request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"  Authorization: Basic {Base64(<client_id>:<client_secret>)}\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_post"]},": Provide the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," as additional parameters in the POST request body."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"jwt-with-shared-key","__idx":2},"children":["JWT with shared key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you configured your client to use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_jwt"]}," client authentication method:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provide the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," in a JWT that you sign with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," using an HMAC SHA algorithm (HS256, HS384, or HS512). The JWT must also contain other values, such as issuer and subject. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#token-claims-for-client-authentication-with-client-secret-or-private-key-jwt"},"children":["Token claims for client authentication with client secret or private key JWT"]},"."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," JWTs with a shared key require a secret that is at least 32 characters in length to satisfy HS256 cryptographic minimums. Clients that attempt to set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_endpoint_auth_method"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_jwt"]}," with an imported secret less than 32 characters will receive a validation error. Clients that send Okta a JWT for verification signed with HS256, HS384, or HS512 with a secret less than 32 characters will receive an error: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["The client secret is too short to verify a JWT HMAC."]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After you create the JWT, in the request you need to specify the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_assertion_type"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["urn:ietf:params:oauth:client-assertion-type:jwt-bearer"]}," and specify the JWT as the value for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_assertion"]}," parameter."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /token HTTP/1.1\nHost: server.example.com\nContent-Type: application/x-www-form-urlencoded\ngrant_type=authorization_code&\n  code=i1WsRn1uB1&\n  client_id=0oajncakofQmjxlSw0h3\n  client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&\n  client_assertion=PHNhbWxwOl ... ZT\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"jwt-with-private-key","__idx":3},"children":["JWT with private key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This method is similar to JWT with shared key, but uses a public/private key pair for more security. The main benefit of this method is you can generate the private key on your own servers and never have it leave there for any reason, since you only need to provide the public key to Okta. This is better than ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_jwt"]}," since Okta must know what the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}," string is beforehand, so there are more places that it could in theory be compromised."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you configured your client to use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["private_key_jwt"]}," client authentication method:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Provide the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," in a JWT that you sign with your private key using an RSA or ECDSA algorithm (RS256, RS384, RS512, ES256, ES384, ES512). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developer-okta.login.adsbillinghub.com/docs/guides/build-self-signed-jwt/"},"children":["Build a JWT for client authentication"]},". The JWT must also contain other values, such as issuer and subject. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#token-claims-for-client-authentication-with-client-secret-or-private-key-jwt"},"children":["Token claims for client authentication with client secret or private key JWT"]},"."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," The private key that you use to sign the JWT must have the corresponding public key registered in the client's ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/okta-oauth/oauth/client/createclient#client/createclient/t=request&path=jwks/keys"},"children":["JWKSet"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After you create the JWT, in the request you need to specify the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_assertion_type"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["urn:ietf:params:oauth:client-assertion-type:jwt-bearer"]}," and specify the JWT as the value for the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_assertion"]}," parameter."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /token HTTP/1.1\nHost: server.example.com\nContent-Type: application/x-www-form-urlencoded\ngrant_type=authorization_code&\n  code=i1WsRn1uB1&\n  client_id=0oajncakofQmjxlSw0h3\n  client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&\n  client_assertion=PHNhbWxwOl ... ZT\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tls-client-certificate","__idx":4},"children":["TLS client certificate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"x-lifecycle","attributes":{"className":"ea"},"children":[]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["mTLS client authentication"]}," is a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developer-okta.login.adsbillinghub.com/docs/concepts/feature-lifecycle-management/#self-service-features"},"children":["self-service Early Access (EA)"]}," feature. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://help-okta.login.adsbillinghub.com/okta_help.htm?id=ext_secur_manage_ea_bata"},"children":["Manage Early Access and Beta features"]}," to enable the feature."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A client secret or JWT assertion proves who's asking for a token, but after Okta issues the token, it's a plain bearer token. This means that anyone who obtains it (such as through an intercepted request or a leaked log) can use it without further proof. mTLS client authentication closes that gap by binding the access token to the TLS certificate that the client presents when the token is requested. When the resource server enforces the binding, a party that obtains the token still needs the certificate's private key to use it. An interceptor can't use the token alone."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you configure your client to use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["self_signed_tls_client_auth"]}," client authentication method, present your client's X.509 certificate during the TLS handshake instead of sending a client secret or JWT assertion. You must include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," in the form-encoded token request body so that Okta can identify the client. Okta validates the certificate with the client's registered ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/okta-oauth/oauth/client/createclient#client/createclient/t=request&path=jwks/keys"},"children":["JWKSet"]},". An mTLS client can't use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["implicit"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["password"]}," grant types, and you can't enable Demonstrating Proof-of-Possession (DPoP) for the client."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because the TLS handshake is involved, you can't present the certificate to the standard token, introspection, or revocation endpoint URLs. Instead, make these requests to the mTLS-capable alias URLs that Okta publishes in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/okta-oauth/oauth/orgas/getwellknownopenidconfiguration#orgas/getwellknownopenidconfiguration/t=response&path=mtls_endpoint_aliases"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mtls_endpoint_aliases"]}]}," object of the OAuth 2.0 or OpenID Connect discovery metadata response. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/okta-oauth/oauth/orgas/getwellknownopenidconfiguration#orgas/getwellknownopenidconfiguration/t=response&path=tls_client_certificate_bound_access_tokens"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tls_client_certificate_bound_access_tokens"]}]}," property in the same response indicates whether the authorization server supports certificate-bound access tokens."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When certificate validation succeeds, Okta issues an access token that's cryptographically bound to the certificate. The token's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cnf"]}," claim contains an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x5t#S256"]}," member with the certificate's base64url-encoded SHA-256 thumbprint. Okta also binds refresh tokens to the certificate, so you must use refresh tokens over mTLS with the same certificate. To enforce the binding, the client must present the same certificate over mTLS when using the token, and the resource server must compare its thumbprint against the token's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cnf.x5t#S256"]}," value and reject requests with a missing or mismatched certificate. Without this check, anyone who obtains the token can use it without the certificate. Validating the token's signature or active status alone isn't sufficient. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/okta-oauth/oauth/orgas/introspect#orgas/introspect/t=response&path=cnf"},"children":["introspection response"]}," for the token includes the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cnf.x5t#S256"]}," value."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"none","__idx":5},"children":["None"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Specify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none"]}," when the client is a public client and doesn't have a client secret. Only the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," is sent in the request body."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"token-claims-for-client-authentication-with-client-secret-or-private-key-jwt","__idx":6},"children":["Token claims for client authentication with client secret or private key JWT"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you use a JWT for client authentication (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret_jwt"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["private_key_jwt"]},"), use the following token claims:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Token Claims"},"children":["Token Claims"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["aud"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required. The full URL of the resource you're using the JWT to authenticate to."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["String"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["exp"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required. The expiration time of the token in seconds since January 1, 1970 UTC."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Integer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["jti"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Optional. The identifier of the token."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["String"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["iat"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Optional. The issuing time of the token in seconds since January 1, 1970 UTC."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Integer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["iss"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required. The issuer of the token. This value must be the same as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["String"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["sub"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required. The subject of the token. This value must be the same as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["String"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Parameter details"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["jti"]}," is specified, the token can only be used once. So, for example, subsequent token requests won't succeed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exp"]}," claim fails the request if the expiration time is more than one hour in the future or has already expired."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iat"]}," is specified, then it must be a time before the request is received."]}]}]},"headings":[{"value":"Client authentication methods","id":"client-authentication-methods","depth":1},{"value":"Client secret","id":"client-secret","depth":2},{"value":"JWT with shared key","id":"jwt-with-shared-key","depth":2},{"value":"JWT with private key","id":"jwt-with-private-key","depth":2},{"value":"TLS client certificate","id":"tls-client-certificate","depth":2},{"value":"None","id":"none","depth":2},{"value":"Token claims for client authentication with client secret or private key JWT","id":"token-claims-for-client-authentication-with-client-secret-or-private-key-jwt","depth":2}],"frontmatter":{"title":"Client authentication methods","category":"authentication","excerpt":"Control user access to your applications.","meta":[{"name":"description","content":"Find information about the OAuth 2.0 and OpenID Connect endpoints that Okta exposes on its authorization servers."}],"seo":{"title":"Client authentication methods"}},"lastModified":"2026-10-16T16:26:18.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/openapi/okta-oauth/guides/client-auth","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}