Authentication

How to authenticate with the Kanoniv API.

Authentication Methods

1. API Key (Recommended)

For programmatic access and integrations. API keys are prefixed with kn_ and scoped per tenant.

Python

from kanoniv.client import KanonivClient

client = KanonivClient(
    api_key="kn_abc123...",
    base_url="https://api.kanoniv.com",
)

# All subsequent calls are authenticated
result = client.resolve(system="Stripe", external_id="cus_123")

curl

curl https://api.kanoniv.com/v1/resolve?system=Stripe&id=cus_123 \
  -H "X-API-Key: kn_abc123..."

Creating an API Key

Via the Dashboard:

1. Go to Settings > API Keys
2. Click Create New Key
3. Select scopes and copy the key (shown only once)

Via the API (admin only):

Python

from kanoniv.client import KanonivClient

client = KanonivClient(api_key="kn_admin_key...", base_url="https://api.kanoniv.com")

key = client.admin.create_api_key(
    name="My Integration",
    scopes=["data"],
)
print(f"New key: {key['api_key']}")  # Shown only once

curl

curl -X POST https://api.kanoniv.com/v1/api-keys \
  -H "X-API-Key: kn_admin_key..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "scopes": ["data"]
  }'

2. JWT Bearer Token

For user sessions and interactive use. Tokens are short-lived (15 minutes) and must be refreshed.

Python

from kanoniv.client import KanonivClient

# If you already have a token (e.g., from a frontend session)
client = KanonivClient(
    access_token="eyJhbGciOiJSUzI1NiIs...",
    base_url="https://api.kanoniv.com",
)

result = client.entities.search(q="[email protected]")

curl

curl https://api.kanoniv.com/v1/[email protected] \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Obtaining a Token

Python

import httpx
from kanoniv.client import KanonivClient

response = httpx.post("https://api.kanoniv.com/v1/auth/login", json={
    "email": "[email protected]",
    "password": "your-password",
})
tokens = response.json()

client = KanonivClient(
    access_token=tokens["access_token"],
    base_url="https://api.kanoniv.com",
)

curl

curl -X POST https://api.kanoniv.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_abc123...",
  "expires_in": 900,
  "token_type": "Bearer"
}

Token Refresh

Python

import httpx

response = httpx.post("https://api.kanoniv.com/v1/auth/refresh", json={
    "refresh_token": "rt_abc123...",
})
new_tokens = response.json()

curl

curl -X POST https://api.kanoniv.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "rt_abc123..."
  }'

Error Handling

Authentication failures raise AuthenticationError in the Python SDK:

from kanoniv import AuthenticationError, ForbiddenError
from kanoniv.client import KanonivClient

try:
    client = KanonivClient(api_key="kn_invalid_key", base_url="https://api.kanoniv.com")
    client.entities.search(q="test")
except AuthenticationError as e:
    print(f"Auth failed: {e}")           # 401 - invalid credentials
except ForbiddenError as e:
    print(f"Access denied: {e}")         # 403 - insufficient permissions

JWT Claims

The JWT payload contains:

{
  "sub": "user_id",
  "email": "[email protected]",
  "tenant_id": "tenant_uuid",
  "role": "admin",
  "exp": 1707134400,
  "iat": 1707133500
}

Claim	Description
sub	User ID
email	User email address
tenant_id	Tenant isolation context (used for RLS)
role	One of: admin, data, viewer
exp	Expiration timestamp (15 minutes from issue)
iat	Issued-at timestamp

API Key Scopes

Scope	Description
admin	Full access including user management and tenant settings
data	Read/write access to entities, rules, sources, and overrides
ingest	Upload data for reconciliation
(empty)	When no scopes are specified, the key has full access

Roles

Kanoniv uses role-based access control (RBAC) with three roles:

Role	Permissions
viewer	Read-only access to entities, rules, sources, audit
data	Viewer permissions + upload data, create rules, create sources
admin	Full access including user management and tenant settings

Security Best Practices

1. Use HTTPS. All API traffic is encrypted over TLS.
2. Rotate API keys. Regularly regenerate production keys.
3. Least privilege. Use minimal scopes for API keys.
4. Secure storage. Never commit keys to version control; use environment variables.

Environment Variable

Store your API key in an environment variable:

import os
from kanoniv.client import KanonivClient

client = KanonivClient(
    api_key=os.environ["KANONIV_API_KEY"],
    base_url=os.environ.get("KANONIV_URL", "https://api.kanoniv.com"),
)

OAuth2 / SSO

For SSO integration (SAML, OIDC), see SSO & SCIM.