Partner Integration API

Authenticate with your 4SEE Partner API key to obtain a JWT, then POST your telemetry data to 4SEE for transformation and processing.

Docs

Explore OpenAPI/Scalar docs for detailed schemas and examples.

Integration API Auth API

Quickstart

  1. Request access and receive your Partner API key.
  2. Call POST /api/v1/partners/authenticate with X-API-KEY.
  3. Store the returned JWT for ~30 minutes (token validity).
  4. POST your telemetry JSON to /api/v1/telemetry/intake/{VIN} with Authorization: Bearer <token>.
  5. Expect HTTP 202 Accepted. 4SEE transforms your payload based on your product permissions.
# Partner auth (curl)
curl -X POST \
  -H "X-API-KEY: <YOUR_PARTNER_API_KEY>" \
  https://auth.groteintegrations.com/api/v1/partners/authenticate

# POST telemetry to Integration API
curl -X POST \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{ ... }' \
  https://<integration-host>/api/v1/telemetry/intake/<VIN>

Authentication

Authenticate

Send your Partner API key via X-API-KEY to receive a JWT (valid ~1800s).

POST https://auth.groteintegrations.com/api/v1/partners/authenticate
Rotate Key

JWT-protected; rate limited (3/hour).

PUT https://auth.groteintegrations.com/api/v1/partners/rotate
Rate limits: Auth 10 req/5 min • Rotate 3 req/hour
Headers: X-API-KEY for auth • Authorization: Bearer <JWT> for all intake calls • Content-Type: application/json required on POST

End-to-End Workflow

Your Grote representative provides a Partner API key along with the product permissions scoped to your integration.

POST to the Auth API with X-API-KEY and receive a short-lived JWT (~30 min). Cache it and refresh proactively before expiration.

POST your JSON payload to POST /api/v1/telemetry/intake/{VIN} with Authorization: Bearer <JWT> and Content-Type: application/json. 4SEE identifies the target product from your token's product:[name] permission and transforms the data accordingly.

A 202 Accepted means your payload was received and queued for processing — not necessarily processed yet. On 400 fix your payload before retrying. On 429 back off and retry. On 401/403 re-authenticate or contact support.

Rotate Partner API keys with the JWT-protected PUT /api/v1/partners/rotate endpoint. Rate limited to 3 requests per hour.
Common HTTP Status Codes
  • 202 Accepted – Payload received and queued
  • 400 Validation Problem – Fix payload before retrying
  • 401 Unauthorized – Missing or invalid JWT
  • 403 Forbidden – Insufficient permissions
  • 429 Too Many Requests – Back off and retry
  • 500 Problem – Contact support

Endpoint Summary

Authentication API
  • POST /api/v1/partners/authenticate → JWT
  • PUT /api/v1/partners/rotate → Rotate API key
Integration API
  • POST /api/v1/telemetry/intake/{VIN}

    Submit telemetry for the given VIN. The product transformation applied is determined by the product:[name] claim in your JWT. Returns 202 Accepted.

Rate Limits & Fair Use

How intake limits work

Intake requests are rate-limited using a fixed window model scoped per product and per VIN. Each product integration has its own limit, so different integrations you operate don't share a quota.

  • Per-product, per-VIN: Limits are tracked independently for each VIN within each product integration. One noisy VIN won't consume quota for others.
  • Fixed window: The request count resets on a fixed time boundary. Requests within the window count against your limit regardless of spacing.
  • Predictable cadence: Design your integration around your device's natural reporting interval. Bursting beyond that won't be absorbed.
  • When you hit the limit (HTTP 429): Wait until the current window expires, then retry. Implement exponential backoff for transient spikes.
Specific limits are determined per product integration at onboarding. Contact 4SEE Support if you need your limits reviewed.

Partner Onboarding

Interested in integrating your telemetry data with the 4SEE platform? The 4SEE team works directly with partners to design and certify new integrations.

Onboarding includes a data format review, schema mapping to the 4SEE model, product permission configuration, and end-to-end validation before going live. Reach out to begin the process.

Contact the 4SEE Team

Support & Best Practices

Best Practices
  • Cache JWTs until expiration; proactively refresh before they expire.
  • Always include Content-Type: application/json on every POST.
  • Treat 202 as acknowledgment only — not confirmation of processing.
  • On 429, implement exponential backoff before retrying.
  • On 400, inspect the response body for validation details and fix the payload before retrying.
  • Secure your Partner API key; use /api/v1/partners/rotate immediately if compromised.
Contact

Questions or onboarding needs?

4SEE Support Team