JSON Web Token (JWT) is an open web standard that's used for authenticating and authorizing information exchanges between a client and a server. When an app user first signs in with the appropriate role credentials, the server creates and returns an encoded, digitally-signed JWT for use with subsequent requests. This process both authenticates the user and authorizes them to access routes, services, and resources based on their account role.
Fleet Engine requires the use of JSON Web Tokens (JWTs) signed by an appropriate service account for API method calls from low-trust environments. Low-trust environments include smartphones and browsers. A JWT originates on your server, which is a fully-trusted environment. The JWT is signed, encrypted, and passed to the client for subsequent server interactions until it expires or is no longer valid.
Your backend should authenticate and authorize against Fleet Engine using standard Application Default Credentials mechanisms. Make sure to use JWTs that have been signed by an appropriate service account. For a list of service-account roles, see Fleet Engine service account roles in Fleet Engine Basics.
Unlike API keys, JWTs are short lived and limit operations to only those that the role is authorized to perform. For more information on JWTs, see JSON Web Tokens on Wikipedia. For detail on access roles, see Service account roles in this guide.
JWT elements
JWTs contain a header and a claim section. The header section contains information such as the private key obtained from service accounts, and the encryption algorithm. The claim section contains information such as the JWT's create time, time to live, the services that the JWT claims access to, and other authorization information to scope access; for example, the delivery vehicle ID.
The following table provides descriptive details about JWT fields in general, as well as specific information about where you can find the values for these fields in your Fleet Engine Cloud project.
Field |
Description |
---|---|
alg |
The algorithm to use. `RS256`. |
typ |
The type of token. `JWT`. |
kid |
Your service account's private key ID. You can find this value in the
|
Field |
Description |
---|---|
iss |
Your service account's email address, found in the
|
sub |
Your service account's email address, found in the
|
aud |
Your service account's |
iat |
The timestamp when the JWT was created, specified in seconds
elapsed since 00:00:00 |
exp |
The timestamp when the JWT expires, specified in seconds elapsed
since |
authorization |
Depending on the use case, may contain If specifying taskids, the authorization scope must be an array in one of the following forms: "taskids": ["task_id_one","task_id_two"]
or "taskids": ["*"] |
Fleet Engine JWT claims
Fleet Engine uses private claims. Using private claims ensures that only authorized clients can access their own data.
For example, when your server issues a JSON Web Token for a driver's mobile
device, it should contain either the vehicleid
claim or the
deliveryvehicleid
claim with the value of that driver's vehicle ID. Then,
depending on the driver role, JWTs enable access only for the specific vehicle
ID and not any other arbitrary vehicle ID.
Fleet Engine uses the following private claims:
On-demand trips
-
vehicleid
:- The Driver SDK always uses this claim, whether operating on a trip or vehicle. The Fleet Engine backend assures that the vehicle is associated with the requested trip before doing the modification.
- As a service provider, you use this claim with a "*" to match all vehicles. Note that the JWT can cover both vehicle and trip operations, even if not required, which may simplify the JWT signing implementation.
-
tripid
:- The Consumer SDK always uses this claim.
- As a service provider you use this claim with a "*" to match all trips. Note that the JWT can cover both vehicle and trip operations, even if not required, which may simplify the token signing implementation.
Scheduled tasks
-
deliveryvehicleid
Use when calling per-delivery-vehicle APIs.
-
taskid
Use when calling per-task APIs.
-
taskids
Use when calling
BatchCreateTasksAPI
. This claim must be in array form, and the array should contain all task IDs necessary to complete the request. Don't includedelivervehicleid
,trackingid
, ortaskid
claims. -
trackingid
Use when calling the
GetTaskTrackingInfoAPI
. The claim must match the tracking ID in the request. Don't includedelivervehicleid
,taskid
, ortaskids
claims.
What's next
- Read about Fleet Engine security design to understand the complete authentication flow.
- Learn how to Issue JSON Web Tokens from your server.