Catena Connect | Catena Telematics API

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.

Fleet Selects TSP

Fleet chooses their telematics service provider from the supported list.

Fleet Provides Credentials

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

Connection Created

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

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.

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

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:

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

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

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