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:

Scope	Permission Level	Description
read:universe	Read-Only	Retrieve auditable entities and organizational hierarchies.
read:findings	Read-Only	Read findings, action plans, and remediation tracker logs.
write:evidence	Write-Only	Upload evidence files and attach them to test procedures.
write:findings	Write/Update	Document findings, submit recommendations, and update action plan statuses.
admin:sync	Full Access	Execute 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.