Overview & Workflow

Authenticate with your 4SEE Customer API key to obtain a JWT, then access fleet, trailer, device, and DeliverSafe data.

Docs

Explore OpenAPI/Scalar docs for detailed schemas and examples.

Integration API Auth API

Quickstart

  1. Request access and receive your Customer API key.
  2. Call POST /api/v1/customers/authenticate with X-API-KEY.
  3. Store the returned JWT for ~30 minutes (token validity).
  4. Call Integration API endpoints with Authorization: Bearer <token>.
  5. Use key rotation when needed via PUT /api/v1/customers/rotate.
# Customer auth (curl)
curl -X POST \
  -H "X-API-KEY: <YOUR_CUSTOMER_API_KEY>" \
  https://auth.groteintegrations.com/api/v1/customers/authenticate

# Use JWT with Integration API
curl -H "Authorization: Bearer <JWT>" \
  https://<integration-host>/api/v1/fleets/?take=50

Authentication

Authenticate

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

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

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

PUT https://auth.groteintegrations.com/api/v1/customers/rotate
Rate limits: Auth 10 req/5 min • Rotate 3 req/hour
Headers: X-API-KEY for auth • Authorization: Bearer <JWT> for all other calls

End-to-End Workflow

Your Grote representative provides a Customer API key.

POST to the Auth API with X-API-KEY and receive a short-lived JWT (~30 min).

Use Authorization: Bearer <JWT> to query fleets, trailers, devices, DeliverSafe, and telemetry-in-scope endpoints.

Use next and take query params for offset/time-based paging. The response includes a next token when more data is available.

Rotate Customer API keys with the JWT-protected PUT /api/v1/customers/rotate endpoint.
Common HTTP Status Codes
  • 200 OK – Success
  • 400 Validation Problem / 500 Problem
  • 401 Unauthorized – Missing/invalid JWT
  • 403 Forbidden – Insufficient permissions
  • 404 Not Found
  • 429 Too Many Requests (rate limits)

Endpoint Summary

Authentication API
  • POST /api/v1/customers/authenticate → JWT (Customers)
  • PUT /api/v1/customers/rotate → Rotate API key
Integration API

  • GET /api/v1/fleets (cursor based, next, take)
  • GET /api/v1/fleets/{fleet}

  • GET /api/v1/trailers/{fleet} (cursor based, next, take, activeOnly)
  • GET /api/v1/trailers/{trailer}
  • GET /api/v1/trailers/telemetry/gps/{trailer} (time-based paging)

  • GET /api/v1/devices/{trailer} (cursor based, next, take, activeOnly)
  • GET /api/v1/devices/details/{device}
  • GET /api/v1/devices/telemetry/{device} (telemetry; time-based)

  • GET /api/v1/deliversafe (cursor based, next, take)
  • GET /api/v1/deliversafe/{id}
  • GET /api/v1/deliversafe/telemetry/{id} (time-based)

Rate Limits & Fair Use

What to expect
  • Per-customer limits: Your traffic is isolated. Other customers can’t affect your limits.
  • Burst-friendly: Your bucket starts full, so short spikes are fine up to your plan’s burst limit.
  • Automatic refills: Tokens are added every second, up to your maximum capacity.
  • When you hit the limit (HTTP 429): Pause briefly and retry.
Concurrency: Each customer's plan determines how many requests can be processed at the same time. Additional requests beyond your plan's limit may be delayed or receive 429 Too Many Requests responses.

REST not what you’re looking for?

Try our LiveFeed for low-latency streaming updates over gRPC.

Explore LiveFeed (gRPC) Download livefeed.proto

Support & Best Practices

Best Practices
  • Cache JWTs until expiration; proactively refresh before they expire.
  • Respect 429 limits; implement exponential backoff.
  • Use take conservatively and follow next tokens for paging.
  • Secure your Customer API key; use the /api/v1/customers/rotate endpoint if compromised.
Contact

Questions or onboarding needs?

4SEE Support Team