API keys provide a secure and flexible way to connect to JQL and execute queries in Antly. By using API keys, you can authenticate your requests, define permissions based on roles, and control access to specific modules and actions within the system. This section explains how to obtain and use API keys to connect to JQL.

1. Obtaining an API Key

Step 1: Access API Key Management

• Log in to your Antly account and navigate to the API Key Management section under your account settings.

Step 2: Generate a New API Key

• Click on the option to generate a new API key. You will be prompted to provide a name for the key and set the permissions that it should have.

Step 3: Define Permissions

• When creating the API key, you can define specific permissions that restrict what the key can do. Permissions are defined based on the module and the actions allowed.
  • Example 1: tickets.Ticket:* — Grants full access to all actions in the Ticket module under the tickets app.
  • Example 2: profile.Customer:create — Grants access only to create operations for customers.

Step 4: Save and Secure the API Key

• Once generated, save the API key securely. The API key is typically shown only once, so be sure to store it in a safe location. If you lose the key, you may need to generate a new one.

2. Connecting to JQL Using an API Key

Once you have an API key, you can use it to authenticate your JQL queries. The API key is typically included in the Authorization header of your HTTP requests.

Example: Including an API Key in a Request

{
    "__meta__": {
        "authenticationClass": "apiKey",
        "intent": "retrieve",
        "namespace": "tickets.Ticket",
        "schema": "model",
        "filter": {
            "status": "open"
        },
        "limit": 10,
        "offset": 0
    },
    "id": null,
    "title": null,
    "description": null,
    "status": null
}

HTTP Headers:

Authorization: Bearer your_api_key_here
Content-Type: application/json

• Authorization Header: The API key is passed in the Authorization header as a Bearer token. Replace your_api_key_here with the actual API key you obtained from Antly.
• Content-Type Header: Typically set to application/json, indicating that the request body is in JSON format.

3. Controlling Access with API Key Permissions

API keys in Antly are powerful tools that allow you to enforce strict access control based on defined permissions. When configuring permissions for an API key, consider the following:

• Wildcard Access: Use the * wildcard to grant full access to all actions within a module.

  • Example: tickets.Ticket:* allows full access (create, read, update, delete) to all tickets.

• Specific Action Access: Limit access to specific actions such as create, read, update, or delete.

  • Example: profile.Customer:create only allows the creation of customer records, without the ability to read, update, or delete.

• Multiple Permissions: You can combine multiple permissions for more granular control.

  • Example: tickets.Ticket:read,profile.Customer:create allows read access to tickets and create access for customers.

Example: API Key with Multiple Permissions

{
    "key": "your_api_key_here",
    "permissions": [
        "tickets.Ticket:read",
        "profile.Customer:create"
    ]
}

In this example, the API key grants read access to the Ticket module and create access to the Customer module.

4. Best Practices for Using API Keys

• Limit Permissions: Only grant the minimum permissions necessary for the API key to perform its intended function. This principle of least privilege reduces the risk of accidental or malicious misuse.

• Rotate API Keys Regularly: Periodically regenerate and update your API keys to enhance security. Ensure that old keys are revoked or deleted to prevent unauthorized access.

• Monitor API Key Usage: Regularly review logs and monitor the usage of your API keys. Look for any unusual activity or patterns that might indicate unauthorized use.

• Securely Store API Keys: API keys should be stored securely in environment variables or secure storage solutions, not hard-coded in your application code.