> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://catena.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server. # Catena Connect Catena Connect is the hosted onboarding flow that enables fleets to securely connect their telematics providers to your platform. When a fleet opens an invitation magic link, they enter Catena Connect to complete the connection process. --- ## How It Works When a fleet clicks an invitation link, they're guided through a streamlined onboarding process: #### Fleet Opens Invitation Fleet clicks the magic link you created via the Organizations API. ![Catena Connect invitation landing page](https://mintcdn.com/catenaclearing/CeWGOuBegQQEwvvj/get-started/_images/onboarding-1-invitation.png?fit=max\&auto=format\&n=CeWGOuBegQQEwvvj\&q=85\&s=ae1ca8c8acc4f1e7c0a35010f476ac7c) #### Fleet Selects TSP Fleet chooses their telematics service provider from the supported list. ![Telematics provider selection screen](https://mintcdn.com/catenaclearing/CeWGOuBegQQEwvvj/get-started/_images/onboarding-3-tsp-menu.png?fit=max\&auto=format\&n=CeWGOuBegQQEwvvj\&q=85\&s=9b7f62a075e0e3b1e7bdefc4f24cbed5) #### Fleet Provides Credentials Fleet enters their TSP credentials (API keys, OAuth tokens, or login credentials depending on the provider). ![TSP credential input form](https://mintcdn.com/catenaclearing/CeWGOuBegQQEwvvj/get-started/_images/onboarding-4-company-creds.png?fit=max\&auto=format\&n=CeWGOuBegQQEwvvj\&q=85\&s=d1b2c11793b6a4e6d52cf9ec13f2baa3) #### Connection Created Catena validates credentials with the TSP, creates the connection, and establishes the share agreement. ![Successful connection confirmation](https://mintcdn.com/catenaclearing/CeWGOuBegQQEwvvj/get-started/_images/onboarding-5-connection-successful.png?fit=max\&auto=format\&n=CeWGOuBegQQEwvvj\&q=85\&s=e17726ff975ff7e252f219a6163e5806) #### Add More TSPs or Complete Fleet can choose to connect additional telematics providers (if they use multiple TSPs) or complete the onboarding process. #### Fleet Redirected Once complete, the fleet is automatically redirected back to your application using the `success_redirect_url` you configured in the invitation. > **Tip** > > **Real-Time Notifications:** Subscribe to webhooks to receive instant notifications when invitations are accepted, share agreements are created, and connections are established. This allows you to track fleet onboarding status in real-time and trigger workflows in your application. [Learn more about webhooks](/api-reference/notifications/webhooks/overview). --- ## Customization Options Catena Connect can be tailored to match your brand and integration requirements: #### White Labeling Customize Catena Connect with your brand colors, logo, and domain to create a seamless experience that feels native to your platform. > **Info** > > Contact your Catena account manager to configure white labeling for your organization. #### Redirect URLs Configure where fleets are sent after completing or abandoning the onboarding flow: * `success_redirect_url` - Where fleets go after successful connection * `failure_redirect_url` - Where fleets go if they cancel or encounter errors Include query parameters to pass context back to your application. #### Limited TSP Selection Control which telematics providers are shown to fleets during onboarding. Useful for: * Piloting with specific TSPs * Industry-specific provider limitations * Custom TSP partnership agreements Two options are available when creating an invitation: * `limit_tsps` - Show **only** the listed providers * `exclude_tsps` - Show all providers **except** the listed ones `limit_tsps` and `exclude_tsps` are mutually exclusive — you can set one or the other on a given invitation, not both. #### Fleet Metadata Pass metadata through the invitation to pre-populate fleet information: * `fleet_ref` - Your internal fleet identifier * `partner_provided_fleet_name` - Fleet company name This data flows through to share agreements and webhook events for easy tracking. --- ## Security & Compliance Catena Connect is designed with security as a top priority: #### Credential Handling * All TSP credentials are encrypted at rest using AES-256 * Credentials are transmitted only over HTTPS * Credentials are never logged or exposed in API responses * Connections can be paused or revoked at any time by the fleet #### Authentication * Magic links are single-use and time-limited (24 hours by default) * Each invitation generates a cryptographically secure pre-registration token for authentication * Links expire automatically after acceptance or expiration * Fleets do not need to sign up (create a username/password) to use Catena Connect #### Data Privacy * Fleets explicitly consent to data sharing during onboarding * Share agreements clearly define what data will be accessed * Fleets can revoke access at any time through Catena Connect * All data access is logged for audit purposes * GDPR and CCPA compliant data handling --- ## Monitoring Fleet Onboarding Track the status of your fleet invitations and connections: ### Via API Query invitation status to see if fleets have completed onboarding: ```bash curl -X GET \ 'https://api.catenatelematics.com/v2/orgs/invitations/{invitation_id}' \ -H 'Authorization: Bearer ' ``` ### Via Webhooks Subscribe to invitation and connection events for real-time updates: Add the callback URL when creating invitations to receive webhook notifications: ```bash highlight={9} curl -X POST \ --url https://api.catenatelematics.com/v2/orgs/invitations \ -H 'Authorization: Bearer ' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "fleet_ref": "", "success_redirect_url": "https://yourdomain.com/onboarding/success", "callback_url": "https://yourdomain.com/webhooks/invitations" }' ``` #### [Webhook Documentation](/api-reference/notifications/webhooks/overview) Learn how to set up, monitor and manage your webhooks. --- ## Best Practices #### Invitation Delivery * **Embed in your product flow**: Display the magic link as a button or redirect in your application for the smoothest experience * **Email with context**: If sending via email, explain what the link does and why you're requesting access * **Track expiration**: Monitor invitation status and resend if needed—invitations expire after 24 hours by default * **Personalize the message**: Include the fleet's name to increase acceptance rates #### Redirect URLs * **Success URL**: Redirect to a confirmation page that explains what happens next (data sync timing, how to view data, etc.) * **Failure URL**: Provide troubleshooting guidance or customer support contact information * **Include state parameters**: Pass `fleet_ref` or other identifiers as query parameters to track which fleet completed onboarding * **Test both paths**: Ensure both success and failure redirects work correctly in your application #### Error Handling * **Monitor declined invitations**: Track which fleets decline and follow up to understand concerns * **Handle expired invitations**: Automatically resend or prompt users to create new invitations * **TSP credential failures**: We provide clear instructions for fleets to obtain the correct credentials from their TSP in our help sidebar --- #### [Contact Support](mailto:support@catenaclearing.io) Have questions or need assistance? Our team is here to help you succeed.