Before you can begin using the authentication system, ensure you have the following tools and environments set up:

Tools or Environments Needed

API Client:
- You will need an API client like Postman or cURL to send HTTP requests for authentication and verification.
Development Environment:
- Ensure you have a development environment set up where you can securely store and manage API tokens, such as an IDE with environment variable support (e.g., Visual Studio Code, IntelliJ IDEA).
Access to the API:
- Ensure you have network access to the API endpoint where the authentication requests will be sent.

Authentication and Setup Instructions

To authenticate a user and verify their authentication, follow these steps:

User Authentication:

Send a POST request to the authentication endpoint with the following JSON payload:
```
{
  "__meta__": {
    "namespace": "system.User",
    "intent": "authenticate",
    "schema": "controller",
    "authenticationClass": "jwt",
    "return": {
      "id": null
    }
  },
  "username": "{{username}}",
  "password": "{{password}}"
}
```
- username: Replace {{username}} with the user's username.
- password: Replace {{password}} with the user's password.
Response:
- Upon successful authentication, the API will return a JSON Web Token (JWT) which can be used for subsequent API requests.
- Store the JWT securely, as it will be needed for verifying authentication and accessing other protected resources.
Verify Authentication:

To verify the user's authentication status, send a request to the verification endpoint. You can either pass the JWT as a Bearer Token in the Authorization header or as a Cookie.

Using Bearer Token:
- Add the following header to your request:
```
Authorization: Bearer <JWT_TOKEN>
```
Using Cookie:
- Include the JWT in the Cookie header:
```
Cookie: jwt=<JWT_TOKEN>
```
Request Payload:
```
{
  "__meta__": {
    "namespace": "system.User",
    "intent": "verify_authentication",
    "schema": "controller",
    "authenticationClass": "jwt",
    "return": {
      "id": null
    }
  }
}
```
Response:
- The API will respond with a confirmation of the authentication status. If the token is valid, the response will include the user's ID or other relevant authentication details.

Important Notes

Security: Always ensure that JWT tokens are stored securely and are not exposed to unauthorized parties.
Token Expiry: JWT tokens may have an expiration time. Ensure you handle token refresh logic if required by your system.

By following these instructions, you can authenticate users and verify their authentication status securely.

Understanding the basic syntax of a JQL query is essential for interacting with Antly's backend effectively. This section covers the general structure of a JQL query and the common JSON schema components used.

Structure of a JQL Query

A JQL query is structured as a JSON object that consists of two main parts: metadata (__meta__) and the data payload. The metadata provides essential information about the query, such as the type of operation and the target resource, while the data payload contains the actual fields and values involved in the operation.

General Structure of a JQL Query:

{
    "__meta__": {
        "authenticationClass": "<authentication_method>",
        "intent": "<action>",
        "namespace": "<module_name>",
        "schema": "<schema_type>",
        "return": { "<return_value>": null }, // Optional, used in create/update to return specific fields
        "filter": { "<filter_criteria>": "<value>" }, // Optional, used in retrieve operations
        "uniqueObject": { "id": "<instance_id>" } // Optional, used in update/retrieveOne/delete operations
    },
    "<field_name_1>": "<field_value_1>",
    "<field_name_2>": "<field_value_2>",
    // Additional fields as needed
}

Example: Creating a Vehicle

{
    "__meta__": {
        "authenticationClass": "jwt",
        "intent": "create",
        "namespace": "fleet.Vehicle",
        "schema": "model",
        "return": { "id": null }
    },
    "gearbox": "automatic",
    "model_colour": "Fleet_ModelColourType",
    "purchase_type": "lease",
    "vin": "1HGCM82633A004352",
    "vrm": "AB12CDE",
    "year": "2024"
}

Common JSON Schema Components

JQL queries use a standard set of JSON schema components to define operations, filter criteria, and data fields. Below are the most commonly used components:

__meta__: This is a required object in every JQL query. It includes metadata about the query, such as:
- authenticationClass: Specifies the authentication method (jwt, session, public, oauth, etc.).
- intent: Indicates the operation type (create, update, retrieve, retrieveOne, deleteOne).
- namespace: Defines the module or resource the operation targets (e.g., fleet.Vehicle).
- schema: Specifies whether the operation targets a model or controller.
- return: (Optional) Specifies which fields should be returned in the response for create or update operations.
- filter: (Optional) Used in retrieve operations to filter results based on certain criteria.
- uniqueObject: (Optional) Used in update, retrieveOne, and deleteOne operations to target a specific resource instance.
Query Data: The fields and values relevant to the operation. These vary depending on the operation being performed:
- Create/Update: Includes fields to be created or updated.
- Retrieve: May include null values to indicate which fields should be returned, and can include nested objects for deeper queries.
- DeleteOne: Typically requires only the unique identifier of the resource.

Example: Updating a Vehicle

{
    "__meta__": {
        "authenticationClass": "jwt",
        "intent": "update",
        "namespace": "fleet.Vehicle",
        "schema": "model",
        "return": { "id": null }
    },
    "gearbox": "manual",
    "model_colour": "Fleet_ModelColourType",
    "purchase_type": "cash",
    "vin": "1HGCM82633A004352",
    "vrm": "XY34ZFG",
    "year": "2025"
}

Example: Retrieving a List of Vehicles

{
    "__meta__": {
        "authenticationClass": "jwt",
        "intent": "retrieve",
        "namespace": "fleet.Vehicle",
        "schema": "model",
        "filter": {
            "purchase_type": "lease"
        }
    },
    "gearbox": null,
    "model_colour": {
        "id": null,
        "colour": null
    },
    "purchase_type": null,
    "vin": null,
    "vrm": null,
    "year": null
}

Example: Deleting a Vehicle

{
    "__meta__": {
        "authenticationClass": "jwt",
        "intent": "deleteOne",
        "namespace": "fleet.Vehicle",
        "schema": "model",
        "uniqueObject": {
            "id": "123456"
        }
    }
}

These examples illustrate how JQL queries are structured and the common JSON components used. By understanding this syntax, you can effectively craft queries to perform various operations within Antly’s system.