{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Token Exchange Flow (External IDP Integration)","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"token-exchange-flow-external-idp-integration","__idx":0},"children":["Token Exchange Flow (External IDP Integration)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This flow allows applications to exchange a valid security token issued by an external Identity Provider (IDP), such as Okta, for an eGain access token. This is ideal for Single Sign-On (SSO) scenarios where you want to leverage existing sessions to call eGain APIs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"_","__idx":1},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prerequisites & Guidelines"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SSO Configuration"]},": The external IDP must be registered and stored in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SSO Provider"]}," configuration section of the Administrator Console."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["User Matching"]},": The user identity (e.g., email) contained within the external token's claims must exist in the eGain database."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Enablement"]},": The Client Application must have the \"Token Exchange Grant Type\" enabled."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"_-1","__idx":2},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exchange an External Token for an eGain Token"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Method"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint"]},": Your Token URL (from your client application's ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/guides/authentication/metadata"},"children":["metadata"]},").",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Example Token URL for a Client App:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token"]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Headers:"]}]},{"$$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":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/x-www-form-urlencoded"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Body Parameters (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/x-www-form-urlencoded"]},"):"]}]},{"$$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":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Relevance"},"children":["Relevance"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Must be set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["urn:ietf:params:oauth:grant-type:token-exchange"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject_token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The valid JWT access token issued by your external IDP (e.g., Okta)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject_token_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The type of token being provided. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["urn:ietf:params:oauth:token-type:access_token"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registration_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The unique identifier generated in the Administrator Console for the external IDP registration."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The eGain Client ID for your application."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Required"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The eGain Client Secret for your application."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Optional"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A space-separated list of eGain scopes requested for the new token."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validation Logic:"]}," During this request, eGain verifies the token's signature using the external IDP's JWK URL, ensures the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["iss"]}," (issuer) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aud"]}," (audience) claims match your registration, and confirms the user exists within eGain."]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Token Exchange cURL:"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl --location --request POST 'https://ai.egain.cloud/system/auth/TMPRODB88619984-U/oauth2/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \\\n--data-urlencode 'subject_token=EXTERNAL_IDP_JWT_TOKEN' \\\n--data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \\\n--data-urlencode 'registration_id=okta_sso_config_01' \\\n--data-urlencode 'client_id=b4b2c1d9-4c19-4e8a-8e7a-9a0b1c2d3e4f' \\\n--data-urlencode 'client_secret=aBcDeFgHiJkLmNoPqRsTuVwXyZ12345'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Next Steps:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/guides/authentication/making-requests"},"children":["Make Authenticated Requests"]}]}]}]},"headings":[{"value":"Token Exchange Flow (External IDP Integration)","id":"token-exchange-flow-external-idp-integration","depth":1},{"value":"","id":"_","depth":2},{"value":"","id":"_-1","depth":2}],"frontmatter":{"seo":{"title":"Token Exchange Flow (External IDP Integration)"}},"lastModified":"2026-05-02T01:39:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-portal/guides/authentication/token-exchange-flow","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}