Authentication
This page explains how to authenticate with the Alvys Public API using the OAuth 2.0 Client Credentials flow.
Update (June 2025): A new token endpoint has been introduced to enhance security and scalability. While the authentication flow remains based on the Client Credentials model, tokens must now be requested from the updated URL.
The legacy
/api/authentication/{tenant_id}/token
based endpoint is deprecated and will be fully shut down on July 31, 2025.
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.
🔐 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.
Curl 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"
}'
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.
🔒 Scope Claim
Note: Although create, update, and delete scopes can be assigned to API clients, only read
access is currently supported by the Alvys Public API. These additional scopes are included for future compatibility and consistency.
Important: Legacy tokens generated through the previous {tenant_id}
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 |
🛑 Legacy Authentication (Deprecated)
This older flow will stop working on July 31, 2025.
Create Client Application
To begin, create a new application from the Alvys Admin page. This will allow you to generate a client_id and client_secret.
client_id
: The unique identifier assigned to this application or caller.client_secret
: A confidential token also provided by Alvys upon application registration.
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.tenant_id
: The tenant ID for which the client application was registered.grant_type
: The type of grant flow to use. Must beclient_credentials
Old Token Endpoint
https://integrations.alvys.com/api/authentication/{TENANT_ID}/token
JSON Format Example
curl --request POST \
--url 'https://integrations.alvys.com/api/authentication/{TENANT_ID}/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"grant_type": "client_credentials"
}'
Form-Encoded Format Example
curl --request POST \
--url 'https://integrations.alvys.com/api/authentication/{TENANT_ID}/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'client_secret=YOUR_CLIENT_SECRET'
🧪 Troubleshooting
- ✅ Double-check your
client_id
,client_secret
, andaudience
- ✅ 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
orapplication/x-www-form-urlencoded
- For technical support: [email protected]
Updated about 11 hours ago