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.

🔐 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

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