By leveraging OAuth 2.0, developers can empower their applications to seamlessly interact with Alvys' API on behalf of their users. This guide outlines the authentication process and provides detailed instructions on obtaining access tokens through direct application integration.

📘
Getting API Access

Existing Alvys customers can obtain API access by contacting their account representative.

Independent Software Vendors (ISV) should contact the Alvys Partnership team.

🔐 Creating Client Application Credentials

Follow these steps to create your credentials in the Alvys Admin Portal:

Navigate to Admin → API Access
Click Create New Application
Fill out the Name and Description
Select your desired permissions (scopes)
Set an optional expiration date for the credentials
Click Generate

After creation, your Client ID and Client Secret will be shown, along with the scopes included for token generation. Customers can generate up to 10 sets of client credentials, but only newly generated ones can be edited.

⚠️
These values are sensitive and must be stored securely—avoid sharing them publicly or exposing them in front-end code.

These credentials are used to request an access token via the issue token endpoint.

Construct Authorization Request

Construct a URL with the following parameters in the request body:

client_id: The unique identifier assigned to your application by Alvys.
client_secret: The confidential token provided by Alvys upon application registration.
audience: Must be "https://api.alvys.com/public/" .
grant_type: The type of grant flow to use. Must beclient_credentials

🔐 New Token Endpoint

All new token requests must now use the following endpoint:

Token URL

https://auth.alvys.com/oauth/token

Request Body (JSON)

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.alvys.com/public/",
  "grant_type": "client_credentials"
}

✅
When including a "scope" field in the token request body, please note:

The returned token will always include all scopes that have been granted to your client application, regardless of what you specify in the scope field.

Therefore, including a scope field in the request does not override or limit the access defined by your assigned permissions in the issued token.

The only functional effect of providing a scope field is that the token request will fail (unauthorized) if you include any scope that has not been granted to your client.

If the scope field is omitted, the token will still include all scopes granted to your application.

Either format may be used (JSON or Form-Encoded) ; both will return the same token and enforce scopes identically.

Curl JSON Content-Type Example

curl --request POST \
     --url 'https://auth.alvys.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '{
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET",
       "audience": "https://api.alvys.com/public/",
       "grant_type": "client_credentials"
     }'

Curl Form-Encoded Format Example

curl --request POST \
     --url https://auth.alvys.com/oauth/token \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data 'client_id=YOUR_CLIENT_ID' \
     --data 'client_secret=YOUR_CLIENT_SECRET' \
     --data 'audience=https://api.alvys.com/public/' \
     --data 'grant_type=client_credentials'

The token you receive will include a scope claim (e.g. "load:read trip:create"), and our Public API enforces those scopes on every request. Use the resulting access token in your API request headers:

Authorization: Bearer YOUR_ACCESS_TOKEN

The client_id and `client_secret are created in the Alvys Admin Portal under API Access.

Postman Token Request Example:

Each client credential’s token is restricted to the exact scopes you assign, ensuring it can only access those corresponding API endpoints.

🚧
Note
While you can assigncreate, update, and delete scopes and your token will include them, the corresponding write endpoints are not yet available. At this time, the Public API only exposes read operations—those additional scopes are in place for seamless adoption once write functionality is release

🔒 Scope Claim

Important: Legacy tokens generated through the previous /api/authentication/{tenant_id}/token authentication flow do not include the scope claim. These tokens will temporarily remain valid and behave as if all read-only scopes are granted, but this is only supported during the transition period. All clients must migrate to the new flow by July 31, 2025 to avoid disruption.

New tokens now follow a fine-grained permissions model, ensuring each application only has access to the specific API features it was granted.

Example:

"scope": "load:read driver:create"

Scopes control access to API endpoints and must be selected when creating your application in the Admin Portal.

Available Scopes

Entity	Permission	Description
Customers	`customer:read`	View customer records
Customers	`customer:create`	Add a customer
Customers	`customer:update`	Edit customer details
Customers	`customer:delete`	Remove a customer
Drivers	`driver:read`	View driver profiles
Drivers	`driver:create`	Add new driver
Drivers	`driver:update`	Edit driver info
Drivers	`driver:delete`	Remove a driver
Fuel	`fuel:read`	View fuel records
Fuel	`fuel:create`	Add fuel transaction
Fuel	`fuel:update`	Update fuel entry
Fuel	`fuel:delete`	Delete fuel record
Invoices	`invoice:read`	View invoices
Invoices	`invoice:create`	Create invoice
Invoices	`invoice:update`	Edit invoice
Invoices	`invoice:delete`	Delete invoice
Loads	`load:read`	Retrieve load info
Loads	`load:create`	Create a load
Loads	`load:update`	Update a load
Loads	`load:delete`	Delete a load
Maintenance	`maintenance:read`	View maintenance data
Maintenance	`maintenance:create`	Log maintenance event
Maintenance	`maintenance:update`	Edit maintenance record
Maintenance	`maintenance:delete`	Remove maintenance record
Tolls	`toll:read`	View toll data
Tolls	`toll:create`	Log toll
Tolls	`toll:update`	Update toll entry
Tolls	`toll:delete`	Delete toll entry
Trailers	`trailer:read`	View trailer info
Trailers	`trailer:create`	Register trailer
Trailers	`trailer:update`	Edit trailer record
Trailers	`trailer:delete`	Remove trailer
Trips	`trip:read`	View trip details
Trips	`trip:create`	Create trip
Trips	`trip:update`	Update trip
Trips	`trip:delete`	Cancel/delete trip
Trucks	`truck:read`	View truck info
Trucks	`truck:create`	Register truck
Trucks	`truck:update`	Update truck record
Trucks	`truck:delete`	Remove truck
Users	`user:read`	View users
Users	`user:create`	Add new user
Users	`user:update`	Modify user
Users	`user:delete`	Remove user
Visibility	`visibility:read`	Access tracking data
Visibility	`visibility:create`	Trigger visibility update
Visibility	`visibility:update`	Modify visibility data
Visibility	`visibility:delete`	Remove tracking entry
Dispatch Preferences	`dispatch:read`	View dispatch rules
Dispatch Preferences	`dispatch:update`	Update dispatch preferences
Carriers	`carrier:read`	View carrier profiles
Carriers	`carrier:create`	Add a new carrier
Carriers	`carrier:update`	Update carrier details
Carriers	`carrier:delete`	Remove a carrier from records

🧪 Troubleshooting

✅ Double-check your client_id, client_secret, and audience
✅ Ensure scopes are correctly assigned in API Access- Admin Portal
✅ Validate that the client is active and not expired
✅ Use only supported content types: application/json or application/x-www-form-urlencoded
For technical support: support@alvys.com