Authentication

Every API route except GET /v1/health and GET /v1/openapi.yaml requires an API key sent in the Authorization header:

Shell

curl https://aicscan.io/v1/workspace \
  -H "Authorization: Bearer aic_k3J9xQ2a_..."

Create a key#

Keys are created from the client area, on the API keys page, by an owner or an administrator of the workspace (a viewer sees the list but can neither create nor revoke):

Give the key a name (1 to 80 characters) saying where it is used: “ERP production”, “Dashboard”.
Choose the scope: read (read only) or read + write (read and modify).
Optionally choose an expiry (30, 90, 180 or 365 days); without one, the key stays valid until it is revoked.
Copy the key that is displayed: it is shown only once.

Creation is refused if the workspace plan does not include the API (plan_required, see Plans and quotas), if the owner account is under review (account_under_review), or if the workspace already has 10 active keys: revoke an unused key first. Every creation and revocation is recorded in the workspace activity log, and owners are notified by email and on the workspace channels.

Key format#

A key is shaped like aic_<prefix>_<secret>:

aic_ lets secret scanners (Git hosting, log tools) recognise it;
the 8-character prefix identifies the key in listings and in the workspace activity log (for example aic_k3J9xQ2a);
the secret is known to you only: Aicscan only stores the SHA-256 hash of the full key.

The full key is shown once, when it is created. A lost key cannot be recovered: create a new one and revoke the old one.

One workspace per key#

A key belongs to a single workspace and only sees its data. A resource of another workspace answers 404 not_found, exactly like a resource that does not exist: its existence does not leak.

Scopes#

Scope	Allowed methods
`read`	`GET` (and `HEAD`)
`write`	`POST`, `PATCH`, `DELETE`

write implies read: a key issued with write gets both scopes. A read-only key that tries to write receives:

JSON

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key lacks the `write` scope.",
    "details": { "required_scope": "write", "key_scopes": ["read"] }
  }
}

The scope required by each endpoint is shown in the reference. The real-time stream requires the read scope.

Good practice

Give each integration its own key with the smallest scope: a read key for a dashboard or an export, a read + write key for the tool that creates rules. If one leaks, you only revoke that one.

Expiry, rotation and revocation#

Expiry: a key can be created with a validity period (30 to 365 days from the client area, 1 to 3,650 days for a key issued by the Aicscan team). After that, it answers 401 api_key_expired.
Rotation: create a new key, deploy it, check that it is used (GET /v1/workspace returns the calling key's prefix in api_key.prefix; the “Last used” column of the API keys page shows it too), then revoke the old one. Both keys work at the same time during the switch.
Revocation: a revoked key stops working immediately (401 api_key_revoked). Real-time connections opened with it are closed at the next check (within 60 seconds, code 4401).

Revocation is done from the API keys page, with a confirmation; it also applies to keys issued for you by the Aicscan team, which appear there with the author “Aicscan team”. Revoke a compromised key without delay. Need help (a key with its own rate limit, a doubt about a use): support@aicscan.io.

Authentication errors#

HTTP	Code	Cause
401	`missing_api_key`	No `Authorization` header, or a scheme other than `Bearer`.
401	`invalid_api_key`	Unknown or malformed key.
401	`api_key_revoked`	Revoked key.
401	`api_key_expired`	Expired key.
403	`workspace_suspended`	Suspended workspace: contact support@aicscan.io.
403	`account_under_review`	The workspace owner account is under review.
403	`plan_required`	The workspace plan does not include the API.
403	`insufficient_scope`	The key lacks the required scope.

401 responses carry a WWW-Authenticate: Bearer realm="aicscan" header (with error="invalid_token" for a rejected key).

Checks run in this order: key, suspended workspace, account under review, plan, rate limit, scope, daily quota. The full list of codes is in Errors.

Account under review#

To prevent multiple accounts, a workspace whose owner is under review, and which has no paid subscription in progress (a trial does not count), receives 403 account_under_review with details.reason = "multi_account_review" on every authenticated route. Access comes back as soon as the Aicscan team approves the account or a paid plan is subscribed.

Keeping keys safe#

Never put a key in code that runs in a browser or a mobile app: it would give access to the whole workspace. Call the API from your server.
Requests are served over HTTPS only.
The last use (date and IP address) of each key is recorded and shown on the API keys page: revoke the key and write to support@aicscan.io about any use you do not recognise.