Logins and sessions

Kismet uses HTTP basic-auth to submit login information, and session tokens to retain login state.

As of 2019-04-git, all interaction with the Kismet server requires a login.

As of 2020-10-git, all endpoints on the Kismet server support a role: All login sessions made with the admin username and password are granted the admin role. The admin role has access to all endpoints. Additional sessions may be set by creating API keys with an assigned role which restricts the available endpoints of the session.

As of 2022-10-git, Kismet uses a JWT system internally to generate session tokens. This change is essentially invisible to users of the API, but alleviates some internal stress on Kismet for retaining a session database and list.

A session will automatically be created during authentication to any endpoint which requires login information, and returned in the KISMET session cookie.

Logins may be manually validated against the /session/check_session endpoint if validating user-supplied credentials.

Providing logins

Kismet accepts logins via HTTP Basic authentication, session cookie, and GET URI parameters.

If the administrator username and password is provided via Basic auth or via get URI parameters, a session cookie is created (if one does not already exist) or found, and returned in the KISMET cookie parameter.

Added 2020-10 API-token-only consumers of the API should provide ONLY the API token given, and supply it in the KISMET cookie or URI parameter.

API Keys

API keys are, essentially, pre-provisioned session tokens stored in the Kismet settings files in the users home directory.

An API key is associated with a role, and can be used with any endpoint which supports that role.

Generally, an API key should be preferred for any tool interacting with Kismet on more than a one-off basis.

URI parameters

Some mechanisms, such as websockets, do not commonly support HTTP Basic Auth or cookie passing, and must use URI parameters:

KeyValue
userAdministrator username
passwordAdministrator password
KISMETKismet session cookie / API token

The same rules apply to the user and password and session token login process - if a valid username and password is provided, it will return a session token in the set-cookie parameter for future logins.

Login roles

As of 2020-10, Kismet supports login roles.

Every endpoint supports one or more roles. The provided authentication, session key, or API key must be authorized for that role or the endpoint will return a permission denied error.

Roles are not inherited; a role limits the API token to those roles.

Logins as the Kismet user are given the role admin, which has access to all endpoints; this retains the standard behavior of endpoints and logins.

The most common use for roles is to limit the access of an API token.

API tokens and roles

As of 2020-11, Kismet supports the use of API tokens and roles to restrict the actions of sessions. Predefined roles include:

RoleDescription
adminMain role with access to all endpoints. Logins created via HTTP auth are automatically assigned the admin role.
readonlyRead-only role with access to endpoints which do not modify any devices, state, or configuration
scanreportRole able to submit device/network scan reports, via the Wi-Fi and Bluetooth scanning-mode API
datasourceRole for remote capture websocket sources

Roles are not inherited or cascading; for instance a readonly role does not have access to reporting scans or acting as remote datasources. The only role with access to all endpoints is admin.

Login and session API

First-time login check

DESC

This API is used by the Kismet web UI, and is available for other alternate full-UI replacements. It is used to indicate if Kismet has been configured fully.

Kismet does not provide a default username or password; instead, if the user has not configured a static account in a configuration file, the UI is expected to prompt the user during the first-tine startup.

The majority of API endpoints will not be available if the account setup process has not been completed.

ROLES
none
ADDED
API added 2019-01
URI
/session/check-setup-ok
METHODS
GET
RETURN
Basic document with success state communicated via HTTP error codes.
RESPONSES
200
If the initial login setup has been completed
406
If the the credentials are hard-coded into a configuration file
ERROR
If the initial setup has not been completed and the user must configure a password to continue
NOTES
If the password is set in the Kismet configuration files, this API will not be available and will return HTTP 406

Set login and password

DESC

Configure the initial login.

This causes Kismet to store the initial login in the settings file in the users home directory.

ROLES
none admin
ADDED
API added 2019-01
URI
/session/set_password
METHODS
POST
POST
PARAMETERS
username string REQUIRED

Username used for standard web login. This user will have the admin role.

password string REQUIRED

Password string for admin user login.

RETURN
Basic document with success state communicated via HTTP error codes.
RESPONSES
200
If the login configuration succeeds
406
If the the server password is hard-coded into a configuration file
ERROR
If the login information could not be set for some other reason
NOTES

Setting the initial password does not require a login.

Subsequent attempts to change the login and password will require a valid login session.

Changing the password does not invalidate any current login sessions.

If the password is set in the global Kismet configuration files, such as kismet_httpd.conf or kismet_site.conf, this API will not be available and will return HTTP 406

Checking sessions

DESC

If a UI or script has a saved session, it can use this endpoint to check if the session is still valid and take an appropriate action (such as using a saved login or prompting the user to log in again) if it is no longer valid.

If basic auth data also provided, a new login will be created and returned if the session is no longer valid.

This endpoint validates login sessions; API keys will not be accepted on this endpoint.

ROLES
admin
URI
/session/check_session
METHODS
GET
RETURN
Empty content, status is communicated via error codes.
RESPONSES
200
If the session is valid or valid login data is provided
ERROR
If the session is not valid and there is no supplied login data or the login data is not valid

Checking login

DESC

A UI or script may need to check for a valid login and prompt the user to take an appropriate action if the login credentials are not valid.

Most likely, the session check API is more appropriate as it will return a valid session simultaneously if the login is valid.

ROLES
none
URI
/session/check_login
METHODS
GET
RETURN
Empty document, results communicated in status codes.
RESPONSES
200
If the login is valid
ERROR
If the login is invalid

Listing API tokens

DESC

Fetch a list of created API tokens, descriptions, and associated roles.

If httpd_allow_auth_view is set to false in the Kismet configuration, the results will not include the API tokens, and the user must look at the Kismet configuration files to view previously created API keys.

ROLES
admin
ADDED
API added 2020-11
URI
/auth/apikey/list.json
/auth/apikey/list.ekjson
/auth/apikey/list.prettyjson
METHODS
GET
RESPONSES
200
JSON array of provisioned API keys
ERROR
On failure

Creating API tokens

DESC

Create a new API token and assign it a role.

New API tokens can only be generated if the httpd_allow_auth_creation option is set to true in the Kismet config. This is set by default.

If httpd_allow_auth_view is not set to true in the Kismet configuration, API tokens may only be viewed at the time of creation, or by inspecting the session file in the users Kismet configuration directory.

ROLES
admin
ADDED
API added 2020-11
URI
/auth/apikey/generate.cmd
METHODS
POST
POST
PARAMETERS
name string REQUIRED

Name of API key; each API key must have a unique name.

role string REQUIRED

Role of API key; this will restrict what the key is allowed to access.

duration string REQUIRED

Duration, in seconds, of token validity, from the time of token creation (now). May be 0 for a permanent token.

RESPONSES
200
On success, a plain-text response of the newly created token
ERROR
On failure to create a token due to improper creation data or other issues
NOTES

httpd_allow_auth_creation must be true or this API will return an error condition.

Users should be prompted to copy the API token at the time of creation.

Revoking API tokens

DESC

Revoke and delete an API token.

All active sessions using the token will be revoked and future sessions prevented.

If httpd_allow_auth_creation is not set in the Kismet configuration, this API will return an error.

ROLES
admin
ADDED
API added 2020-11
URI
/auth/apikey/revoke.cmd
METHODS
POST
POST
PARAMETERS
name string REQUIRED

Name of API token to revoke

RETURN
Empty document, success communicated in status codes.
RESPONSES
200
On success
ERROR
On failure