Azuga APIs use an OAuth 2.0–based authentication mechanism that combines user credentials with client-specific credentials to securely generate an access token. Authentication requests include the required credentials transmitted securely over HTTPS using HTTP headers.

Once an access token is issued, it must be included in the headers of every subsequent API request. This token uniquely identifies both the authenticated user and the client application, enabling secure access to authorized API endpoints.

This approach allows backend services, integrations, and automated scripts to authenticate on behalf of a specific user while maintaining strong client-level security.

Authentication Endpoint

To access Azuga APIs, you must first authenticate using the Authentication API. This endpoint validates your credentials and returns an access token required for all subsequent API calls.

Prerequisites

Before generating an authentication or access token, please ensure you have the following details ready:

1. Valid Azuga User Credentials
An existing Azuga customer account with a username and password.

2. Client API Key
A unique client identifier issued by Azuga. To obtain your Client ID, contact [email protected]

3. Client Secret
A confidential key associated with your Client ID, used for secure authentication. To obtain your Client Secret, contact [email protected]

Having these prerequisites in place will ensure a smooth and successful access token generation process.

The OAuth Flow

Once you have received your clientApiKey and clientSecret, a successful authentication between your application, the user, and the Azuga Auth service occurs in the following order:

1. Make an authentication request to the Azuga Login API.Your application sends a secure request to the Azuga authentication endpoint: https://fleet-rest.azuga.com/api/v4/login.
2. Your application sends the request with:
   • Authorizationheader containing the Base64-encoded username:password
   • clientApiKey and clientSecret headers

Note:To obtain your clientApiKey and clientSecret, please contact [email protected]

3. Azuga validates the credentials and client keys.
4. On successful validation, the API responds with an access token, refresh token, and expiry information.
5. Your application uses the access token to authenticate subsequent Azuga API requests.

Authorization Request

The first step in the Azuga authentication flow is making a login request to the Azuga Authentication API. This request validates the user credentials along with client-specific keys and generates an access token for subsequent API calls.

Authentication request URL: https://fleet-rest.azuga.com/api/v4/login.

Example Request: GET https://fleet-rest.azuga.com/api/v4/login

Authorization Header Details

To generate the Authorization header:

1. Combine the username and password using a colon (:) Example: [email protected]:test123
2. Encode the combined string using Base64. You may use any Base64 encoder. . Example: EpvaG5AYXp1Z2EuY29tOnRlc3QxMjM=
3. Prefix the encoded value with the word Basic followed by a space. Example: Authorization: Basic EpvaG5AYXp1Z2EuY29tOnRlc3QxMjM=

Example Request:

curl --request GET \
     --url https://fleet-rest.azuga.com/api/v4/login \
     --header 'Authorization: Basic cGhhbmlrQGF6dWdhLmNvbTpUZXN0aW5nQDEy' \
     --header 'accept: application/json' \
     --header 'clientApiKey: tfhhbmlrRGF6dWdhLmNvbTp0XEN0aW5nQDwT' \
     --header 'clientSecret: qjhhbmlrUGI6dWdhLmNvbTp0XEN0aV5nQKwP'

Example Response:

On success, the API returns HTTP status 200 (OK).

{
  "message": "Access Token Fetched Successfully.",
  "generatedAt": 1681072293000,
  "data": {
    "accessToken": "MR1ny07tErdg4nIKlSOfy9Typ9yCyeDK",
    "refreshToken": "TfEK0w0gj4ZkZ8Ub70IcrMwX8MGHGF6N",
    "expiresIn": 15552000
  }
}

Success Response Structure

On successful authentication, the API returns an access token that can be used to authorize subsequent API requests.

Refresh Token Request and Response

Once your access token expires after 180 days, you can use the Refresh Token API to generate a new access token and refresh token without re-authenticating with username and password.

The refresh token is issued as part of the Authentication API response and can be reused until it expires or is revoked.

Request Structure

The HTTP verb for this request is GET, and the refresh token URL is:https://fleet-rest.azuga.com/api/v4/refresh-token

Example Request

curl --request GET \
     --url 'https://fleet-rest.azuga.com/api/v4/refresh-token?refreshToken=qjhhbmlrUGI6dWdhLmNvbTp0XEN0aV5nQKwP' \
     --header 'Authorization: Bearer qjhhbmlrUGI6dWdhLmNvbTp0XEN0aV5nQKwP' \
     --header 'accept: application/json'

Response Structure

On success, the API returns HTTP status 200 (OK) and the following data in the response body:

Example Response

{
  "message": "Refreshed Tokens Fetched Successfully.",
  "generatedAt": 1681072293000,
  "data": {
    "accessToken": "MR1ny07tErdg4nIKlSOfy9Typ9yCyeDK",
    "refreshToken": "TfEK0w0gj4ZkZ8Ub70IcrMwX8MGHGF6N",
    "expiresIn": 15552000
  }
}

Use the Access Token

For all other API calls, include the access token in the header:

Authorization: Bearer <accessToken>

Example:Authorization: Bearer MR1ny07tErdg4nIKlSOfy9Typ9yCyeDK

Error Codes

The possible errors you can get are:

Error Response

{
  "errorMessage": "INVALID-REQUEST",
  "generatedAt": 1681072293000,
  "description": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "errorDetails": [
    {
      "field": "username",
      "description": "Required input parameter is missing or invalid. username should be of a string dataType.",
      "code": "AZGAS-001"
    },
    {
      "field": "password",
      "description": "Required input parameter is missing or invalid. password should be of a string dataType.",
      "code": "AZGAS-004"
    }
  ]
}

{
  "errorMessage": "UNAUTHORIZED",
  "generatedAt": 1681072293000,
  "description": "User is not Authorized. Ensure that the authorization header in your request is included and valid.",
  "errorDetails": [
    {
      "field": "username/password",
      "description": "Required input parameter is missing or invalid. Could not find the user account for given userName and password.",
      "code": "AZGAS-005"
    },
    {
      "field": "Authorization",
      "description": "Invalid Authorization, Authorization header should be 'Basic' Authorization in format 'Basic Base64(username:password)'..",
      "code": "AZGAS-008"
    }
  ]
}

{
  "errorMessage": "INTERNAL-SERVER-ERROR",
  "generatedAt": 1681072293000,
  "description": "Service is currently unavailable. Please try again later."
}

{
  "generatedAt": 1708676216236,
  "errorMessage": "FORBIDDEN",
  "description": "You don't have the necessary permissions to perform this action. Please ensure you have the required privileges.\""
}