Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
openapi: 3.2.0
info:
title: KernelScan Auth API
description: 'Public REST API for KernelScan — the Linux kernel CVE analyzer. Upload a kernel .config and get a CycloneDX VEX report of affecting CVEs, query the CVE database, and manage product analyses. Authenticate with `Authorization: Bearer ks_live_` (create one at /api/auth/api-keys). The same surface is also available over MCP at /mcp/.'
version: 1.0.0
contact:
name: KernelScan Support
url: https://kernelscan.io/docs
email: support@kernelscan.io
termsOfService: https://kernelscan.io/agb
servers:
- url: https://kernelscan.io
tags:
- name: Auth
description: Registration, login, API keys, and account management.
paths:
/api/auth/register:
post:
tags:
- Auth
summary: Register
operationId: register_api_auth_register_post
responses:
'201':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Register Api Auth Register Post
/api/auth/request-invitation:
post:
tags:
- Auth
summary: Request Invitation
description: 'Public application form. Returns 202 generically — does not leak whether
the email is already a user, already has a pending request, etc.'
operationId: request_invitation_api_auth_request_invitation_post
responses:
'202':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Request Invitation Api Auth Request Invitation Post
/api/auth/invitations:
get:
tags:
- Auth
summary: List My Invitations
operationId: list_my_invitations_api_auth_invitations_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response List My Invitations Api Auth Invitations Get
post:
tags:
- Auth
summary: Create Invitation
operationId: create_invitation_api_auth_invitations_post
responses:
'201':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Create Invitation Api Auth Invitations Post
/api/auth/invitations/accept:
post:
tags:
- Auth
summary: Accept Team Invitation
description: 'Seat the logged-in caller into the team a code invites them to.
The counterpart of register()''s team branch for an email that is already an
account (backend#323 slice 2). Same code rows, same email-bound lookup —
the difference is that the account exists, so the seating goes through
:func:`app.services.team_service.add_member` exactly as the admin console''s
does: products follow when the move empties the caller''s personal team, and
the seat limit is enforced under the team-row lock in the same transaction
as the seat write (other *pending* invites never block an accept).'
operationId: accept_team_invitation_api_auth_invitations_accept_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Accept Team Invitation Api Auth Invitations Accept Post
/api/auth/login:
post:
tags:
- Auth
summary: Login
operationId: login_api_auth_login_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Login Api Auth Login Post
/api/auth/refresh:
post:
tags:
- Auth
summary: Refresh
operationId: refresh_api_auth_refresh_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Refresh Api Auth Refresh Post
/api/auth/logout:
post:
tags:
- Auth
summary: Logout
description: 'Close the user''s active session, invalidate issued tokens, emit an event.
Bumping ``token_version`` makes this a logout-*all*: every access/refresh
token minted before this call (on any device) fails the ''tv'' check in
:func:`app.auth.get_optional_user` / the refresh endpoint (backend#288).'
operationId: logout_api_auth_logout_post
responses:
'204':
description: Successful Response
/api/auth/verify-email:
post:
tags:
- Auth
summary: Verify Email
operationId: verify_email_api_auth_verify_email_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Verify Email Api Auth Verify Email Post
/api/auth/resend-verification:
post:
tags:
- Auth
summary: Resend Verification
description: 'Mail a fresh confirmation token to the signed-in account''s address.
Registration was the only place that ever sent one, which left an
unverified account with nothing to do but hunt for a mail that may be days
old — and signing in again does not help, since login never asked for
verification in the first place. Anything that locks a viewer out on
``is_email_verified`` needs this to point at.
Deliberately NOT the enumeration-proof shape ``forgot-password`` uses: the
caller is already authenticated, so there is no address to confirm or deny
the existence of, and the honest 429 is worth more than a fake 200. The
address is the account''s own — never taken from the request — so this
cannot be turned into a mailer for someone else''s inbox.'
operationId: resend_verification_api_auth_resend_verification_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Resend Verification Api Auth Resend Verification Post
/api/auth/forgot-password:
post:
tags:
- Auth
summary: Forgot Password
operationId: forgot_password_api_auth_forgot_password_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Forgot Password Api Auth Forgot Password Post
/api/auth/reset-password:
post:
tags:
- Auth
summary: Reset Password
operationId: reset_password_api_auth_reset_password_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Reset Password Api Auth Reset Password Post
/api/auth/me:
get:
tags:
- Auth
summary: Me
operationId: me_api_auth_me_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Me Api Auth Me Get
/api/auth/newsletter:
put:
tags:
- Auth
summary: Set Newsletter Pref
description: 'Give or withdraw consent to product news.
``require_user``, not ``require_verified_user``: withdrawal must be at least
as easy as giving consent (Art. 7(3)), and an unverified account that ticked
the box at signup has to be able to take it back. One toggle, no
confirmation step, no reason asked.'
operationId: set_newsletter_pref_api_auth_newsletter_put
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Set Newsletter Pref Api Auth Newsletter Put
/api/auth/request-tier:
post:
tags:
- Auth
summary: Request Tier
operationId: request_tier_api_auth_request_tier_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Request Tier Api Auth Request Tier Post
/api/auth/api-keys:
get:
tags:
- Auth
summary: List Api Keys
operationId: list_api_keys_api_auth_api_keys_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response List Api Keys Api Auth Api Keys Get
post:
tags:
- Auth
summary: Create Api Key
operationId: create_api_key_api_auth_api_keys_post
responses:
'201':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Create Api Key Api Auth Api Keys Post
/api/auth/account:
delete:
tags:
- Auth
summary: Delete Account
operationId: delete_account_api_auth_account_delete
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Delete Account Api Auth Account Delete
/api/auth/api-keys/{key_id}:
delete:
tags:
- Auth
summary: Revoke Api Key
operationId: revoke_api_key_api_auth_api_keys__key_id__delete
parameters:
- name: key_id
in: path
required: true
schema:
type: string
title: Key Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Revoke Api Key Api Auth Api Keys Key Id Delete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/auth/api-keys/{key_id}/permanent:
delete:
tags:
- Auth
summary: Purge Api Key
description: 'Hard-delete a revoked API key, removing the audit row entirely.
Soft revocation (`DELETE /api-keys/{id}`) is the default — it preserves
the row so prefix and last-used timestamp stay visible for audit. This
endpoint physically removes the row, but only for keys that are already
revoked, to prevent accidental loss of an active credential.'
operationId: purge_api_key_api_auth_api_keys__key_id__permanent_delete
parameters:
- name: key_id
in: path
required: true
schema:
type: string
title: Key Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Purge Api Key Api Auth Api Keys Key Id Permanent Delete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/auth/feed-url-token:
get:
tags:
- Auth
summary: Get Feed Url Token
description: 'Return metadata for the user''s active feed URL token, or 404 if none.
The raw token is **never** returned here — it is only revealed at creation
or rotation time.'
operationId: get_feed_url_token_api_auth_feed_url_token_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Get Feed Url Token Api Auth Feed Url Token Get
post:
tags:
- Auth
summary: Create Or Rotate Feed Url Token
description: 'Mint a new feed URL token, soft-revoking any existing active one.
Optional JSON body ``{"series": ["mainline", "6.6", …]}`` scopes the feed
to those kernel series (backend#272). Each requested series is validated
against the caller''s plan via :func:`_feed_series_options` (the same
resolved set analytics uses); free is locked to ``mainline``. Omitting
``series`` leaves the token unscoped (paid keeps the full feed; free is
clamped to mainline at request time).
Returns the raw token exactly once; subsequent GETs only show metadata.'
operationId: create_or_rotate_feed_url_token_api_auth_feed_url_token_post
responses:
'201':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Create Or Rotate Feed Url Token Api Auth Feed Url Token Post
delete:
tags:
- Auth
summary: Revoke Feed Url Token
description: Soft-revoke the user's active feed URL token. 404 if none.
operationId: revoke_feed_url_token_api_auth_feed_url_token_delete
responses:
'204':
description: Successful Response
/api/auth/totp/setup:
post:
tags:
- Auth
summary: Totp Setup
description: 'Begin TOTP enrollment. Returns a fresh secret + otpauth URI.
Calling this while a half-finished secret exists (totp_enabled=0,
secret!=NULL) **rotates** to a new secret — simplest UX and the old
secret was never confirmed.'
operationId: totp_setup_api_auth_totp_setup_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Totp Setup Api Auth Totp Setup Post
/api/auth/totp/confirm:
post:
tags:
- Auth
summary: Totp Confirm
description: Finalize TOTP enrollment. Verifies a code, flips enabled, returns backup codes.
operationId: totp_confirm_api_auth_totp_confirm_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Totp Confirm Api Auth Totp Confirm Post
/api/auth/login/totp:
post:
tags:
- Auth
summary: Login Totp
description: Exchange a one-shot MFA challenge token + a TOTP/backup code for access tokens.
operationId: login_totp_api_auth_login_totp_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Login Totp Api Auth Login Totp Post
/api/auth/totp/disable:
post:
tags:
- Auth
summary: Totp Disable
description: Disable TOTP. Requires password + a valid TOTP code or backup code.
operationId: totp_disable_api_auth_totp_disable_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Totp Disable Api Auth Totp Disable Post
/api/auth/totp/backup-codes/regenerate:
post:
tags:
- Auth
summary: Totp Regenerate Backup Codes
description: Replace the user's backup-code set. Requires password + valid TOTP code.
operationId: totp_regenerate_backup_codes_api_auth_totp_backup_codes_regenerate_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Totp Regenerate Backup Codes Api Auth Totp Backup Codes Regenerate Post
/api/auth/totp/forgot:
post:
tags:
- Auth
summary: Totp Forgot
description: 'Email-recovery for a lost authenticator. Requires email AND current password.
Always returns 200 — and always runs bcrypt against either the real hash
or a dummy — so neither the existence of the account nor whether 2FA is
on can be inferred from response timing.'
operationId: totp_forgot_api_auth_totp_forgot_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Totp Forgot Api Auth Totp Forgot Post
/api/auth/totp/reset:
post:
tags:
- Auth
summary: Totp Reset
description: Consume a one-time reset token (from email) and disable TOTP on the account.
operationId: totp_reset_api_auth_totp_reset_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Totp Reset Api Auth Totp Reset Post
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
externalDocs:
description: KernelScan documentation
url: https://kernelscan.io/docs