Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
1

Fleet Opens Invitation

Fleet clicks the magic link you created via the Organizations API.
Catena Connect invitation landing page
2

Fleet Selects TSP

Fleet chooses their telematics service provider from the supported list.
Telematics provider selection screen
3

Fleet Provides Credentials

Fleet enters their TSP credentials (API keys, OAuth tokens, or login credentials depending on the provider).
TSP credential input form
4

Connection Created

Catena validates credentials with the TSP, creates the connection, and establishes the share agreement.
Successful connection confirmation
5

Add More TSPs or Complete

Fleet can choose to connect additional telematics providers (if they use multiple TSPs) or complete the onboarding process.
6

Fleet Redirected

Once complete, the fleet is automatically redirected back to your application using the success_redirect_url you configured in the invitation.
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.

​
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.
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

Restrict which telematics providers are shown to fleets during onboarding. Useful for:
  • Piloting with specific TSPs
  • Industry-specific provider limitations
  • Custom TSP partnership agreements
Configure via the limit_tsps parameter when creating invitations.

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:
  • 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
  • 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
  • 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: 
curl -X GET \
  'https://api.catenatelematics.com/v2/orgs/invitations/{invitation_id}' \
  -H 'Authorization: Bearer <token>'

​
Via Webhooks

Subscribe to invitation and connection events for real-time updates: Add the callback URL when creating invitations to receive webhook notifications: 
curl -X POST \
  --url https://api.catenatelematics.com/v2/orgs/invitations \
  -H 'Authorization: Bearer <token>' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "fleet_ref": "<your internal fleet id>",
  "success_redirect_url": "https://yourdomain.com/onboarding/success",
  "callback_url": "https://yourdomain.com/webhooks/invitations"
}'

Webhook Documentation

Learn how to set up, monitor and manage your webhooks.

​
Best Practices

  • 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
  • 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
  • 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

Have questions or need assistance? Our team is here to help you succeed.