{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/custom-cards/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"OAuth","description":"Start building with the Dixa API","siteUrl":"https://docs.dixa.io/","keywords":"dixa developer hub, api portal starter, api reference docs","lang":"en-US","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":"oauth","__idx":0},"children":["OAuth"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OAuth is an authorization standard widely used among bigger companies like Google, Apple, and Facebook. OAuth offers a higher level of security than tokens because the OAuth tokens are automatically refreshed, and you can limited with a scope."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dixa supports ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authorization Code Flow"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Credentials Flow"]}," as OAuth strategies. The third party service determines the choice."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisite","__idx":1},"children":["Prerequisite"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The connecting API must support OAuth 2"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You need to be a workspace admin in Dixa to create a custom card"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setting-up-the-application","__idx":2},"children":["Setting up the application"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Because of the secure nature of an OAuth application, it's necessary to configure both sides of the transaction. The third party is the application, and Dixa is the user."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Dixa backend handles the grant and can be ignored when configuring OAuth in Dixa."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Part of the Dixa OAuth feature is to refresh tokens automatically."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"application-with-code-flow","__idx":3},"children":["Application with code flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You will need to obtain the following at the third party for an authorization code flow:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["client ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["client secret"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Scope"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Authorization Endpoint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Token Endpoint"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Applications will ask for a redirect URL, which is always the same for Dixa custom cards. Insert the following into the third-party setup:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://partner-integrations.dixa.io/auth/provider/callback\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A scope can limit access to areas of an API. If you take Google as an example, a scope for their calendar will look like this:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://www.googleapis.com/auth/calendar.readonly"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["And with Hubspot, a scope for OAuth and CRM objects looks like this:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oauth crm.objects.contacts.read"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The third-party typically generates the client ID and secret, which are unique in syntax and length."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"set-up-dixa","__idx":4},"children":["Set up Dixa"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Dixa, we must match the scope, client ID, and secret from the third party."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/oauth.afecc10cfeb004bdbc4a17bd810ee36075cc07798001358374f3b84f77d83e8e.fcd6b147.png","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The third party defines the authorization and token endpoints and can usually be found in the documentation or when configuring the token/app."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After you have populated the necessary fields, you save the information by clicking ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save configuration"]}," and then proceed by selecting ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authorize"]},". A pop-up will open asking you to sign in (if you're not already signed in with the third party). You must click on both the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save configuration"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authorize"]}," buttons."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"application-with-credential-flow","__idx":5},"children":["Application with credential flow"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because of the secure nature of an OAuth application, it's necessary to configure both sides of the transaction. The third party is the application, and Dixa is the user."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You will need to obtain the following at the third party for a credential code flow:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["client ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["client secret"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Authorization Endpoint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Token Endpoint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Scope"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Audience"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Applications will ask for a redirect URL, which is always the same for Dixa custom cards. Insert the following into the third-party setup:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://partner-integrations.dixa.io/auth/provider/callback\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A scope can limit access to areas of an API. If you take Google as an example, a scope for their calendar will look like this:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://www.googleapis.com/auth/calendar.readonly"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["And with Hubspot, a scope for OAuth and CRM objects looks like this:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oauth crm.objects.contacts.read"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The third-party typically generates the client ID and secret, which are unique in syntax and length."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The audience should be referencing Dixa."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"set-up-dixa-1","__idx":6},"children":["Set up Dixa"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Dixa, we must match the scope, client ID, and secret from the third party.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/oauth2.2f861a74c88dda5270c37419526f3adc7a35e16d03ac03641e734ef3e37d70c6.fcd6b147.png","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The third party defines the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authorization Endpoint"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Token Endpoint"]},". Both can usually be found in their documentation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scope"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Audience"]}," are optional for an OAuth flow but can be required from a third party. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://community.auth0.com/t/what-is-the-audience/71414"},"children":["Auth0"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.ory.sh/docs/hydra/guides/audiences"},"children":["Ory"]},", and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://mojoauth.com/glossary/jwt-audience/"},"children":["MojoAuth"]}," have great reads on their implementation of the audience, which can be used to get a better understanding."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After you have populated the necessary fields, you save the information by clicking ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save configuration"]}," and then proceed by selecting ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authorize"]},". A pop-up will open asking you to sign in (if you're not already signed in with the third party). You must click on both the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save configuration"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authorize"]}," buttons."]}]},"headings":[{"value":"OAuth","id":"oauth","depth":1},{"value":"Prerequisite","id":"prerequisite","depth":2},{"value":"Setting up the application","id":"setting-up-the-application","depth":2},{"value":"Application with code flow","id":"application-with-code-flow","depth":3},{"value":"Set up Dixa","id":"set-up-dixa","depth":4},{"value":"Application with credential flow","id":"application-with-credential-flow","depth":3},{"value":"Set up Dixa","id":"set-up-dixa-1","depth":3}],"frontmatter":{"seo":{"title":"OAuth"}},"lastModified":"2026-04-09T11:32:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/custom-cards/authorization-oauth","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}