Skip to main content
Version: 1.0.0-beta

API Keys Management

API keys allow external programs, automation scripts, and custom integrations to securely authenticate and interact with the AIIA REST API.

AIIA provides granular, scope-restricted API keys to enforce role-based access control (RBAC) and data isolation (multi-tenancy) for external programmatic clients.


Key Lifecycle & States​

API keys exist in one of the following lifecycle states:

  • Active: The key is valid and can be used to authenticate requests matching its defined scopes.
  • Expired: The key has passed its set expiration date and will be rejected automatically.
  • Revoked: The key was manually deactivated by an administrator. Revocation is immediate and permanent.

Granular Scopes​

When creating an API key, you must assign one or more scopes. Keys can only execute operations permitted by their assigned scopes:

ScopePermission LevelDescription
read:universeRead-OnlyRetrieve auditable entities and organizational hierarchies.
read:findingsRead-OnlyRead findings, action plans, and remediation tracker logs.
write:evidenceWrite-OnlyUpload evidence files and attach them to test procedures.
write:findingsWrite/UpdateDocument findings, submit recommendations, and update action plan statuses.
admin:syncFull AccessExecute data refresh connectors and sync organizational structures.

[!IMPORTANT] Tenant Isolation: All API keys are tied to a specific Organization (Tenant). An API key generated for Org A cannot read or write data for Org B, even if it has wildcard or admin scopes. RLS (Row-Level Security) is automatically enforced on the database level.


Generating an API Key​

  1. Navigate to Settings → API Keys.
  2. Click the Generate Key button.
  3. Provide a descriptive label (e.g., ServiceNow Integration Key) and select an expiration period (30 days, 90 days, 1 year, or Custom).
  4. Select the specific scopes required for the integration.
  5. Click Generate.
  6. Copy the API key value immediately.

[!CAUTION] For security reasons, the complete API key is only shown once upon creation. It will not be retrievable from the database later.


Authentication Reference​

To authenticate API requests, include the API key in the Authorization header of all HTTP requests:

GET /api/v1/findings HTTP/1.1
Host: aiia.organization.com
Authorization: ApiKey aiia_key_live_5f9d2e1c...
Accept: application/json

Python Example​

import requests

url = "https://aiia.organization.com/api/v1/findings"
headers = {
"Authorization": "ApiKey your_api_key_here",
"Accept": "application/json"
}

response = requests.get(url, headers=headers)
if response.status_code == 200:
findings = response.json()
print(f"Successfully retrieved {len(findings)} findings.")

Security Best Practices​

  • Key Rotation: Rotate API keys at least every 90 days.
  • Least Privilege: Assign only the absolute minimum scopes required for the integration to function.
  • Secret Storage: Store API keys securely in a vault (e.g., HashiCorp Vault, AWS Secrets Manager, or GitHub Secrets). Never commit raw API keys to version control.
  • API Key Masking: In the AIIA dashboard, API keys are always masked (e.g., •••••{last4}) to prevent shoulder-surfing exposure.