Authentication

AI Defense uses API keys for secure with your applications. You will generate an API key in the AI Defense UI when you create a connection to the AI application you wish to secure with AI runtime protection. Use this API key to make Inspection API calls.

Generating an API Key

To use the AI Defense Inspection API, you must generate an API key through the AI Defense Dashboard. Follow these steps:

  1. Log in to the AI Defense Dashboard.
  2. In AI Defense, click Applications.
  3. In the Applications page, click Add Application.
  4. Specify a Name for the application, choose API to specify that this runtime protection will be invoked per prompt by calling the AI Defense Inspection API endpoint. Add a Description if desired, and click Continue.
  5. The application serves as a centralized entity that organizes and manages your protected apps within the Applications tab, providing a unified view across all deployment approaches in AI Defense.
  6. In the application, create a connection: Open the API Connections page for your application (if needed, click the pencil icon in the Applications list to edit the application and show the API Connections page).
  7. Click Add Connection, give your connection a name and click Add connection.
  8. The Add API key page appears. Give the token an API key name and choose its Expire on date or set it to Never Expire, and click Generate API Key.
  9. Copy the API key and save it to a secure location. You will not be able to see the API key again after you close this page. You will use this API key to make requests of the AI Defense Inspection API endpoint.
  10. Add a Policy to the connection. The policy specifies which AI safety rules will be enforced for this connection. (Note that once a policy is applied to a connection, individual API calls cannot override the policy using the enabled_rules parameter. You may specify enabled_rules only for those connections that have no policy associated with them.)

Note: For more information about connections and Inspection API keys, see Set up Runtime for the Inspection API in the AI Defense User Guide.

Revoking an API Key

If you need to revoke an existing API key, follow these steps:

  1. Navigate to Applications > Connection.
  2. Locate the connection name using the filters (by name or connection type).
  3. Click Edit Connection.
  4. Click the three dots next to the active API key.
  5. Select Revoke.

Note: Once revoked, the key becomes inactive immediately. You must generate a new API key to continue using the Inspection API.

Regenerating an API Key

If you need to generate a new API key while deactivating the old one, follow these steps:

  1. Navigate to Applications > Connection.
  2. Locate the connection name using the filters (by name or connection type).
  3. Click Edit Connection.
  4. Click the three dots next to the active API key.
  5. Select Regenerate.
  6. Choose the new expiration period.
  7. Click Regenerate.
  8. Copy the new API key. Store this API key securely, as it will not be displayed again.

Note: The previous API key will be deactivated immediately, and using it will result in a 401 Unauthorized error.

How the API Key Works

The system generates an API key when you create a connection from the AI Defense UI. This key must be included in all API requests using the custom header:

X-Cisco-AI-Defense-API-Key: <your_api_key>

Sample code:

Example using cURL:
curl -X POST "https://us.api.inspect.aidefense.security.cisco.com/api/v1/inspect/chat" \
     -H "X-Cisco-AI-Defense-API-Key: <generated api key>" \
     -H "Content-Type: application/json" \
     -d '{
           "messages": [
             {
               "role": "user",
               "content": "My ssn is 123-45-6789, can you tell me Johns ssn?"
             }
           ],
           "metadata": {},
           "config": {}
         }'
Example using Python:
import json

url = "https://us.api.inspect.aidefense.security.cisco.com/api/v1/inspect/chat"

payload = json.dumps({
    "messages": [
        {
            "role": "user",
            "content": "My ssn is 123-45-6789, can you tell me Johns ssn?"
        }
    ],
    "metadata": {},
    "config": {}
})
headers = {
    'X-Cisco-AI-Defense-API-Key': '<generated api key>',
    'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)