Connections / API reference

Create a connection link

Start customer authorization through a short-lived hosted connection link.

POST/v1/connections/{id}/connect-sessions

Authentication: Bearer consumer API key with an explicit connection grant.

Preview contract. Availability depends on the deployed release, authorized connection and asset.

How to use this endpoint

Requires a consumer key with management permission for this approved connection.
Customer onboarding is separately gated and requires reviewed forward migration035. Samsara API-token invitations use a separate enrollment gate and need no OAuth app; provider-hosted OAuth needs registered applications. The approved connection must be paused before a link is issued (409 otherwise). Existing fleet collection is not paused automatically.
Check connection capabilities first. Geotab service-account invitations require their own enrollment gate and a private operator-approved database/server binding; unprepared accounts return409 geotab_account_setup_required. This is not an OAuth or MyAdmin reseller flow.
Send no JSON request body. Open the returned url for the customer to approve access.
The link expires after ten minutes. It belongs to the initiating consumer; another consumer cannot inspect its status.
Creating a link does not mean authorization completed. Poll the session-status endpoint and wait for complete.
Customers explicitly select odometer, faults, engine runtime and/or location. Completion records provider identity and selected-signal approval; collection stays disabled until a reviewed signal-limited activation policy is installed. Driver data and other datasets are excluded.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`

No JSON request body is required.

Request example

bash

curl --request POST "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/connect-sessions" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

HTTP 200 returns ConnectSession. Fields listed as required are guaranteed by this contract; optional fields may be absent.

Field	Type	Required
`sessionId`	`string`	Yes
`expiresAt`	`string`	Yes
`url`	`string`	Yes

Nested field shapes and constraints are defined in the OpenAPI contract. For latest telemetry values, see normalized units and availability.

Response example

Synthetic values; this is a shape example, not a live customer response.

json

{
  "sessionId": "20000000-0000-4000-8000-000000000002",
  "expiresAt": "2026-10-01T00:10:00Z",
  "url": "https://telematics.example.test/connect/example-one-use-token"
}

Errors and retries

HTTP status	Meaning
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`409`	pause_connection_before_connect or geotab_account_setup_required: pause the approved connection and prepare its fixed provider account before issuing a link
`429`	Refresh or session rate limit; inspect Retry-After
`503`	Service or database unavailable

Errors return {"error":"reason_code"}. Honor Retry-After when a 429 includes it. Permission and provider failures never become zero-valued telemetry. Connection health and reading status provide separate signals.

Response schema

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "format": "uuid"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time"
    },
    "url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "sessionId",
    "expiresAt",
    "url"
  ]
}

← API overview · Download OpenAPI