Fleet Intelligence Platform on AWS Part 2— Fleet Management API
Background
For a full background of the project series read this post.
The GitHub repository for this project is available here.
A dispatcher starting a shift needing vehicle status. An ops admin updating a truck’s region after a maintenance stop needs something different. An auditor pulling records for a GDPR subject access request needs something different again. Each represents a different person, a different permission boundary, and a different audit obligation.
The question is not how to build an API. It is how to enforce those boundaries without standing credentials, manual IAM management, or audit trails that regulators cannot read.
This post covers the operational control plane for TrackHaul’s fleet: the API through which operators query vehicle records, and the access model that governs who can do what.
What was built
Cognito as the identity boundary. The operator authenticates against a Cognito user pool and receives an ID token valid for one hour. That token is presented on every API call. No standing IAM users exist. No shared API keys are issued. There are no long lived credentials to rotate.
API Gateway as the enforcement point. Token validation happens at the gateway before the request reaches any compute. An unauthenticated request is rejected with a 401 at this layer. Lambda never sees it. Every request that reaches the application layer is attributable to a named, authenticated identity.
Lambda as the query handler. The function receives the truck ID from the request path, queries DynamoDB by primary key, and returns the vehicle record. The DynamoDB table name is injected as an environment variable, encrypted by the same customer managed KMS key that protects the table.
DynamoDB as the vehicle records store. The table uses on demand billing. Vehicle records are keyed by truck ID. Three operator groups are defined in Cognito: ops admin, dispatcher, and auditor. Group membership travels in the JWT token with every request.
All resources are deployed in eu-central-1. The full Terraform implementation is available on GitHub.
Architecture
Operator query path
Operator ->Cognito user pool. A dispatcher or ops admin authenticates with email and password. Cognito issues a signed JWT ID token valid for one hour. The token carries group membership ops admin, dispatcher, or auditor embedded as a claim. This is the only credential the operator holds.
Cognito ->API Gateway. The operator presents the token in the Authorization header. API Gateway validates the signature and expiry against the Cognito user pool before any further processing. A request without a valid token is rejected here. No compute is invoked. No database is touched.
API Gateway ->Lambda. A validated request carries the full event context into the Lambda handler, including the truck ID from the path and the decoded JWT claims. The function has no awareness of unauthenticated traffic that has already been filtered.
Lambda ->DynamoDB. The handler queries the vehicle records table by primary key. The table is encrypted with a customer managed KMS key. The Lambda execution role has decrypt access to that key and read access to that table only. Nothing else.
Get Nityananda’s stories in your inbox
Join Medium for free to get updates from this writer.
DynamoDB ->Operator. The vehicle record is returned: truck ID, make, model, plate, region, and status. No PII. No location data. The response travels back through Lambda and API Gateway to the operator.
Key decisions and why
Regional endpoint, not edge. API Gateway supports two endpoint types: Regional and Edge. Edge endpoints route traffic through CloudFront points of presence, some of which sit outside the EU. For a platform where data residency is enforced at the SCP level, an Edge endpoint creates a compliance gap at the first hop. A Regional endpoint keeps all traffic within eu-central-1 from the moment it leaves the operator’s device.
Cognito groups, not custom authorisers. A custom Lambda authoriser offers finer grained control over authorisation logic but introduces a moving part that requires maintenance, versioning, and its own failure mode. Cognito group membership embedded in the JWT token gives API Gateway everything it needs to enforce role boundaries without additional compute. The authorisation logic is declarative and auditable without reading code.
On demand DynamoDB, not provisioned capacity. Dispatcher query patterns at this stage of the platform are not established. Provisioned capacity requires a traffic baseline to size correctly. Undersizing causes throttling under burst. Oversizing pays for idle capacity overnight when trucks are parked. On demand billing removes that decision and scales to actual usage without intervention.
One Lambda function per endpoint, not a monolithic handler. Each endpoint has its own function with its own scoped execution role. The IAM role for the vehicle query function has access to the vehicle records table and nothing else. A monolithic handler serving multiple endpoints would require a role with access to every resource any endpoint touches.
Customer managed KMS key, not AWS managed. An AWS managed key is simpler to provision but the key policy is not under the operator’s control. A customer managed key carries an explicit key policy naming exactly which principals can encrypt and decrypt, scoped to the Lambda execution role and the DynamoDB service. Annual rotation is enabled. This is the correct boundary for a regulated data store.
Scope
This component covers a single read endpoint: GET /fleet/{truckId}. The endpoint count is a scope decision, not an architectural limitation. The Cognito group structure, the KMS encryption boundary, the IAM execution role pattern, and the API Gateway authorisation model are all in place. Additional endpoints follow the same pattern without changes to any of the underlying security or access control infrastructure.
The Cognito app client is configured with ALLOW_USER_PASSWORD_AUTH for testing. In a deployment serving real operators this would be replaced with ALLOW_USER_SRP_AUTH, which does not transmit the password over the wire. The authorisation model and group structure are unaffected by this change.
Vehicle records contain truck ID, make, model, plate, region, and status. No driver names, personal identifiers, or location coordinates are stored in this table. The absence of PII from the records store is a design constraint that carries forward into every subsequent component in the platform.
Business impact
Dispatchers need vehicle status before every cross border run. Without an operational API, that means raising an engineering request and making decisions on stale data. At 10,000 trucks across three countries, that dependency does not scale.
The access model here removes the engineering bottleneck without replacing it with a credential management problem. Cognito tokens expire after one hour. A dispatcher who leaves the organisation loses access the moment their account is disabled. There are no API keys to track down and no IAM users to clean up across accounts.
The GDPR angle is straightforward. Every request is authenticated, every identity is attributable, and every action lands in CloudTrail. That is the audit trail a regulator expects. Shared credentials and standing IAM users cannot produce it.
On cost, on demand DynamoDB and Lambda mean the bill follows actual usage. No provisioned capacity sitting idle overnight when trucks are parked. At current scale that is a small number. Across a full 10,000 truck deployment it is a line item worth controlling from the start.
What comes next
The next part in the series covers the event driven processing pipeline EventBridge, SQS, Lambda consumers, and Step Functions for incident orchestration.
The GitHub repository for this project is available here
