Authentication

🔄

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.

🔐 Creating Client Application Credentials

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

1. Navigate to Admin → API Access

2. Click Create New Application

3. Fill out the Name and Description

4. Select your desired permissions (scopes)

5. Set an optional expiration date for the credentials

6. 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:

1. client_id: The unique identifier assigned to your application by Alvys.
2. client_secret: The confidential token provided by Alvys upon application registration.
3. audience: Must be "https://api.alvys.com/public/" .
4. 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

🛑 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:

1. client_id: The unique identifier assigned to your application by Alvys.
2. client_secret: The confidential token provided by Alvys upon application registration.
3. tenant_id: The tenant ID for which the client application was registered.
4. 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, 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: [email protected]