Open in ChatGPT
View as Markdown

Authentication

Every authenticated route on the Not AI Public REST API is gated by a aik_v1_* API key. The only unauthenticated routes are /health, /openapi/v3.json, and /swagger.

Key format

API keys are opaque strings that start with the literal prefix aik_v1_. The full key is exactly 47 characters: the 7-character prefix plus a 40-character base64url body. Do not parse the body; treat the whole string as a secret credential.

aik_v1_<40-char base64url body>

Keys are minted in the Not AI dashboard at dash.isnotai.com and are bound to:

  • One integration. The integration the key resolves to is what /v1/integration returns, and is the implicit scope of every list endpoint.
  • One region. Keys do not cross regions. See Region binding below.

The dashboard displays the full key once at creation time. After that, only a masked form is shown (the exact mask is set by the dashboard; the apiKeyMasked field on GET /v1/integration returns the same masked value the dashboard renders).

Presenting the key

The API accepts the key in either of two headers. Pick one per request.

Authorization: Bearer aik_v1_<your-key>

x-api-key: aik_v1_<your-key>

Authorization: Bearer is the modern preference and the one shown in every example in these docs. x-api-key exists for environments where Authorization is reserved or stripped (some corporate load balancers, some serverless gateways, some on-prem proxies will strip or rewrite Authorization before it reaches the application). If both headers are present, Authorization wins.

# Bearer form (preferred)
curl https://api.isnotai.com/v1/integration \
  -H "Authorization: Bearer $ISNOTAI_API_KEY"

# x-api-key form (use when Authorization is unavailable)
curl https://api.isnotai.com/v1/integration \
  -H "x-api-key: $ISNOTAI_API_KEY"

Failure modes

Authentication failures return a 401 with the error envelope. The code is always INVALID_API_KEY, regardless of the underlying reason:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The presented API key is missing, malformed, or unknown."
  }
}

This is intentional. The validator is timing-safe and does not distinguish between “no key was presented,” “the key did not start with aik_v1_,” “the key was the right shape but does not exist,” and “the key exists but belongs to a different region.” All four return the same status, the same code, and the same message. Customers can rotate keys without worrying that the error response leaked information about which keys are valid.

The response may also carry WWW-Authenticate: Bearer (set on early rejection when the request omits the header or presents a malformed value) so HTTP clients can react to the challenge in the standard way.

Region binding

Not AI runs two fully isolated Production stacks, US and EU. A key minted under the US dashboard cannot be used against the EU stack and vice versa.

The practical consequences:

Key minted in Authenticates against
US dashboard https://api.isnotai.com only
EU dashboard https://api-eu.isnotai.com only

Presenting a US key to https://api-eu.isnotai.com returns 401 INVALID_API_KEY, the same envelope you would get for a typo. There is no cross-region routing and no fallback. If you operate in both regions, mint one key per region from the appropriate dashboard.

Rotation and revocation

If a key may be compromised, rotate it immediately:

  1. Sign in to dash.isnotai.com.
  2. Open the integration the key belongs to.
  3. Create a new key.
  4. Update your application’s secret store with the new value.
  5. Revoke the old key from the same panel.

Revocation is effective on the next request. Once revoked, the old key returns 401 INVALID_API_KEY like any other unknown credential.

Operational hygiene

  • Store the key in an environment variable or secret manager. Never commit it to source control, never embed it in a browser bundle, and never paste it into a public ticket.
  • Consider a separate key per environment (development, staging, production) so rotating one does not disturb the others.
  • Consider a separate key per consuming application or agent so revoking one does not cascade.

What the key authorizes

A valid aik_v1_* key authorizes read access to the data the underlying integration already owns. It does not authorize:

  • Writes of any kind (there are no mutating endpoints in v1).
  • Account management, subscription changes, key rotation, alert configuration, exports, or any other dashboard surface.
  • Access to data belonging to other integrations or other tenants.

For anything beyond read-only access to your own data, use the dashboard.