API Keys

API keys provide authentication credentials for external integrations. Each key has a public identifier (the key) and a private secret used for HMAC signature generation.

Key Format

Component	Format	Example
API Key	tk_live_ + 40 hex chars	tk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
API Secret	64 hex chars	e3b0c44298fc1c149afbf4c8996fb924...
Key Prefix	tk_live_ + 8 hex chars	tk_live_a1b2c3d4 (visible in dashboard)

Important: The full API key and secret are only shown once at creation time. Store them securely immediately. If you lose the secret, you must rotate the key to get a new one.

Managing Keys via Dashboard

API keys are managed in Settings → API Keys in the Tiqora dashboard. You need the tenant_admin or super_admin role.

Creating a Key

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Enter a descriptive name (e.g., "Production CRM", "Staging Sync")
4. Optionally set permissions, rate limit, and expiration date
5. Click Create
6. Copy both the API Key and API Secret from the confirmation dialog

Revoking a Key

1. Find the key in the list
2. Click the Revoke button
3. Confirm the action

Revoked keys immediately stop working. Any requests using the revoked key will receive a 401 Unauthorized response.

Rotating a Key

If a secret is compromised or you want to periodically rotate credentials:

1. Find the key in the list
2. Click Rotate
3. Confirm the action — the old secret stops working immediately
4. Copy the new secret from the dialog
5. Update your application with the new secret

Warning: Rotation is immediate. The old secret stops working the moment you rotate. Plan your deployment accordingly.

Managing Keys via API

API key management endpoints require JWT authentication (dashboard session). They are not available through HMAC authentication.

List Keys

GET /api/v1/api-keys

{
  "data": [
    {
      "id": "01912345-5555-7abc-def0-123456789abc",
      "name": "Production CRM",
      "key_prefix": "tk_live_a1b2c3d4",
      "permissions": ["tickets:read", "tickets:write"],
      "rate_limit": 500,
      "is_active": true,
      "last_used_at": "2025-01-15T09:30:00Z",
      "expires_at": null,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Create Key

POST /api/v1/api-keys

{
  "name": "Staging Integration",
  "permissions": ["tickets:read", "customers:read"],
  "rate_limit": 100,
  "expires_at": "2025-12-31T23:59:59Z"
}

Response (201) — includes the secret shown only once:

{
  "data": {
    "id": "01912345-6666-7abc-def0-123456789abc",
    "name": "Staging Integration",
    "key_prefix": "tk_live_b2c3d4e5",
    "permissions": ["tickets:read", "customers:read"],
    "rate_limit": 100,
    "is_active": true,
    "expires_at": "2025-12-31T23:59:59Z",
    "created_at": "2025-01-15T12:00:00Z",
    "api_key": "tk_live_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1",
    "api_secret": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456"
  }
}

Revoke Key

DELETE /api/v1/api-keys/{id}

Returns 204 No Content on success.

Rotate Key

POST /api/v1/api-keys/{id}/rotate

Returns the key data with a new api_secret (shown only once).

Security Best Practices

1. Use separate keys per environment — Create distinct keys for development, staging, and production. This way, revoking one doesn't affect the others.

2. Set expiration dates — For temporary integrations or contractor access, set an expiry date so keys auto-deactivate.

3. Use minimal permissions — Only grant the permissions each integration actually needs.

4. Monitor last_used_at — Unused keys may indicate abandoned integrations. Revoke keys that haven't been used in months.

5. Rotate regularly — Set a rotation schedule (e.g., quarterly) as part of your security practices.

6. Never commit secrets to version control — Use environment variables or secret managers (AWS Secrets Manager, HashiCorp Vault) to store API secrets.

7. Store secrets securely — Never log, email, or expose API secrets in client-side code. They should only exist on your backend servers.