Authorize with Hosted Link

See how to integrate Hosted Link into your authorization flow

Codat recommends Link SDK

Instead of Hosted Link, use the Link SDK to fully embed our flexible, white-labeled auth flow in your application.

You will benefit from our extensive experience combined with authorization best practices, providing your users with a native feeling of the auth flow that achieves an 89% conversion rate on average.

Overview

If you're not able to use our Link SDK, you can choose Hosted Link as your out-of-the-box authorization solution built, provided, and hosted by Codat.

To connect your customers' financial software with Hosted Link, you can:

Direct your customer from your existing app to the Hosted Link auth flow programmatically, or
Manually share the Link URL with your customer.

Indicative demo

Curious where Codat's Hosted Link flow might fit in your customer's experience? See how a fictional fintech company uses it in our demo.

Integrate Link in your app

First, create a company to represent your SMB in Codat. We recommend doing that at the time your SMB user signs up within your app. This way, you can track their connection status from day one.

To create a new company, use the Create company endpoint and provide a name for the company in the request body. For details on managing and deleting existing companies, review Manage companies with our API.

Use your customer's ID for the company name

For the company name parameter, we recommend you pass the ID that you use for the customer in your internal system. This makes it easier to identify the Codat company that corresponds to your record of the customer.

Review the parameters in the example response to creating a new company:

{
  // companyId - retain this
  "id": "1126743b-113d-4d72-b14f-36d6742df487",
  "name": "Superapp",
  "platform": "",
  // redirect - use to redirect your customer to Hosted Link
  "redirect": "https://link.codat.io/company/1126743b-113d-4d72-b14f-36d6742df487",
  "dataConnections": [],
  "created": "2022-05-16T14:55:21.6076495Z"
}

From the response, retain the following:

companyId, because you will need it for directing your customers to Link and managing their connections;
redirect URL value, because you will use this URL in your app to direct the customer to start their Link journey.

Once your customer finishes the Link flow, they will be redirected back to the URL you have set in the Link settings. You can also present your customer with a confirmation screen that shows the platforms they have linked.

Monitor the connection status

To enhance your Hosted Link experience, set up a webhook for when a user authorizes a data connection of the newly created company so that you can action it within your app.

Manage existing users with active connections

Direct the user to the redirect Link URL that you can retrieve from a company's metadata. This allows them to modify their existing connections via the Hosted Link UI.

If you create a new company and establish a new connection for a customer previously connected, you may be billed for it based on your contract.

Manage existing users with pending connections

When a user initiates a connection but fails to authorize access to their financial platform, a data connection is created in a pending status in the respective Codat company.

In this scenario, allow your user to authorize this connection by sending them directly to the third-party authentication screen. Use the linkUrl value from the dataConnections array in the company's metadata. This will prompt the user to authorize the connection to their financial platform.

Use URL to initiate Link

You can request additional security measures within Hosted Link. Link URLs can have a one-time password (OTP) added as a query parameter to limit the validity and number of uses of these URLs. Contact your account manager if you want to enable these measures.

Link validity

Link URLs enhanced by OTPs behave as follows:

Your customers aren't able to use the same Link URL more than once.
Company-specific and connection-specific Link URLs expire after one day even if they weren't used.

Use the Hosted Link URL

Use the Hosted Link URL if your customer's connection is meant to be persistent, and your customer may need to view or update their connection in the future.

To initiate the flow, follow these steps:

Create a company via Portal for your customer.
Navigate to the Companies page in the Portal.
Find the company that you created for the customer, and click Request data next to the company name.
Copy the Link URL from the box that appears and share it with the customer. This will allow the customer to create and authorize a data connection.

If a user already has an integration connection that hasn't been authorized and is not in an active state, click the integration name and copy the URL from the Connections section instead of the Link URL. Share this link with the user to allow them to authorize the specific connection.

Connection URL modal to manage an existing connection

Query parameters in Link URLs

If your application already adds query parameters to Link URLs (for example, by appending ?link.showSandboxIntegrations=false), confirm that your code can handle URLs that already contain query strings.

Use the Invite company URL

Not compatible with OTPs

By default, Hosted Link has an additional authorization enabled that uses OTPs. As a result, it's not possible to use the generic Invite company button to invite your customers to share their data.

Contact your account manager if you want to disable these measures.

We recommend using the Invite company URL if both of these criteria apply to your use case:

You want to onboard a large number of new companies without needing to specify company names or references, and
Your company and your customer do not need to manage, view, or update connections in the future.

To obtain the Invite company URL, navigate to the Companies page in the Codat Portal and click the Invite company button. Before sharing the URL, check that you have customized the Link flow as desired.

Customize the Link flow

Our Link settings allow you to configure the authorization process based on your data needs and manage Link's visuals to suit your brand. You can customize these settings in the Codat Portal in Settings > Auth flow > Link.

We provide detailed instructions on the use of each setting in our documentation:

Limitations

Note the following limitations of the Hosted Link solution:

Hosted Link is not compatible with iframes because this is against our security policies.
Some users may be concerned sharing their data at a codat.io domain. Consider warning them about visiting a third-party website for the authorization process.

To avoid these, try our Link SDK solution instead.

Authorize with Hosted Link

Overview

Integrate Link in your app

Monitor the connection status

Manage existing users with active connections

Manage existing users with pending connections

Use URL to initiate Link

Use the Hosted Link URL

Use the Invite company URL

Customize the Link flow

Limitations

Read next

Contents

Overview​

Integrate LinkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. in your app​

Monitor the connectionConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform. status​

Manage existing users with active connectionsConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform.​

Manage existing users with pending connectionsConnection A link between a Codat company and a data source (like an accounting platform). Each connection represents authorized access to pull or push data from that platform.​

Use URL to initiate LinkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat.​

Use the Hosted LinkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. URL​

Use the Invite companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. URL​

Customize the LinkLink The authorization flow that allows end users to connect their accounting, banking, or commerce platforms to your application via Codat. flow​

Limitations​

Read next​

Contents

Overview

Integrate Link in your app

Monitor the connection status

Manage existing users with active connections

Manage existing users with pending connections

Use URL to initiate Link

Use the Hosted Link URL

Use the Invite company URL

Customize the Link flow

Limitations

Read next