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 APIAuth 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.
ShellRaw HTTP
# 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

Using .NET? The C# SDK does steps 2 through 5 for you.

Prefer a native SDK?

Skip the token handling and paging loops. Our official SDK exchanges your API key for a JWT, refreshes it, follows cursor pagination, and retries transient failures for you.

C# is available today. Additional language SDKs are planned.

C#Every trailer, paging handled
builder.Services.AddDaas(o => o.ApiKey = apiKey);

await foreach (var trailer in daas.Trailers.StreamAsync(fleet: 1234))
    Console.WriteLine(trailer.UnitId);
Explore the SDKs

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 the next and take query params for cursor and time-based paging. When more data is available the response carries a nextCursor value; pass it back as next to fetch the following page. Resend the same filters on every request.

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 or invalid JWT
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Unknown resource, or one outside your fleet
  • 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 (cursor based, fleet, next, take, activeOnly, status, vin, unitId)
  • GET /api/v1/trailers/{trailer}
  • GET /api/v1/trailers/telemetry/gps/{trailer} (time-based paging, next, take, speedThreshold)

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

  • GET /api/v1/deliversafe (cursor based, fleet, next, take, activeOnly, vin, unitId)
  • GET /api/v1/deliversafe/{id}
  • GET /api/v1/deliversafe/telemetry/{id} (time-based paging, next, take, speedThreshold)

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
  • Use the official SDK where one exists; it handles token caching, paging, and retries for you.
  • Cache JWTs until expiration; proactively refresh before they expire.
  • Respect 429 limits; pause briefly and retry with exponential backoff.
  • Use take conservatively and follow nextCursor values for paging.
  • Secure your Customer API key; use the /api/v1/customers/rotate endpoint if compromised.
Contact

Questions or onboarding needs?

4SEE Support Team