Ctrlk
User ManualRelease NotesDeveloper
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Authentication

Request a token

post
/v1/auth/token/request

Initiate a request to obtain an authentication token for accessing protected API endpoints. In order to perform authenticated operations, you must first obtain a token by calling this endpoint. If the request is denied, Fotokite Live may prompt the operator for authorization, depending on system configuration. The Fotokite API key can be provided via basic auth or in the request body.

Authorizations
AuthorizationstringOptional

Provide a Fotokite API key as a HTTP basic auth password (user name is ignored).

Body

Request to obtain a session token. Compatible with OAuth2 client_credentials flow.

grant_typestringOptional

OAuth2 flow type, only "client_credentials" is supported.

Example: client_credentials
client_idstringOptional

Ignored (For OAuth compatibility)

client_secretstringRequired

Fotokite API key. Contact Fotokite support to get an API key assigned and activated for your systems.

Example: 1234567890qwertyuiop
scopestringOptional

Available OAuth2 scopes:

  • read - Grants access to retrieve system data and information.
  • control - Allows sending commands to control the system.
  • can_override - Allows to make handoff/control/override call to override current controlling client.
  • experimental - Enables access to experimental API features.
  • internal - Fotokite-internal functions. Not for third-party use.
token_namestringOptional

Name of the token for display to the operator if there can be multiple sessions per plugin.

Example: Flight Controller
Responses
200

Token issued

application/json

OAuth2 compatible access token response.

idstringRequired

Unique ID of the session, used to identify the session in the system.

Example: 234
plugin_idstringRequired

Unique ID of the plugin (API) key used to create this session.

Example: pluginAB
plugin_namestringOptional

Name of the plugin (API) key used to create this session.

Example: Plugin AB
scopesstring[]Required

Scopes granted to this session token.

Example: ["read","control"]
namestringOptional

Name of the session for display to the operator.

Example: Flight Controller
valid_untilstring · date-timeOptional

Timestamp when this token expires and will no longer be valid.

created_atstring · date-timeRequired

Timestamp when this token was created.

access_tokenstringRequired

Token to use for future requests.

Example: ABCD-WXYZ-1234-5678-PQRS
post/v1/auth/token/request
POST /api/v1/auth/token/request HTTP/1.1
Host: 192.168.2.100:3128
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 145

{
  "grant_type": "client_credentials",
  "client_id": "",
  "client_secret": "1234567890qwertyuiop",
  "scope": "read control",
  "token_name": "Flight Controller"
}
{
  "id": 234,
  "plugin_id": "pluginAB",
  "plugin_name": "Plugin AB",
  "scopes": [
    "read",
    "control"
  ],
  "name": "Flight Controller",
  "valid_until": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "access_token": "ABCD-WXYZ-1234-5678-PQRS"
}

Invalidate a token

post
/v1/auth/token/invalidate

Invalidate the token used for calling the endpoint.

Authorizations
OAuth2clientCredentialsRequired

Plugin authentication using Bearer token. For more details, see Fotokite API Documentation.

Token URL:
Responses
200

Token invalidated

No content
post/v1/auth/token/invalidate
POST /api/v1/auth/token/invalidate HTTP/1.1
Host: 192.168.2.100:3128
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Get active tokens

get
/v1/auth/tokens

Returns a list of active tokens

Required scopes
This endpoint requires the following scopes:
  • : Grants access to retrieve system data and information.
Authorizations
OAuth2clientCredentialsRequired

Plugin authentication using Bearer token. For more details, see Fotokite API Documentation.

Token URL:
Responses
200

List of sessions

application/json

OAuth2 compatible access token response.

idstringRequired

Unique ID of the session, used to identify the session in the system.

Example: 234
plugin_idstringRequired

Unique ID of the plugin (API) key used to create this session.

Example: pluginAB
plugin_namestringOptional

Name of the plugin (API) key used to create this session.

Example: Plugin AB
scopesstring[]Required

Scopes granted to this session token.

Example: ["read","control"]
namestringOptional

Name of the session for display to the operator.

Example: Flight Controller
valid_untilstring · date-timeOptional

Timestamp when this token expires and will no longer be valid.

created_atstring · date-timeRequired

Timestamp when this token was created.

access_tokenstringRequired

Token to use for future requests.

Example: ABCD-WXYZ-1234-5678-PQRS
get/v1/auth/tokens
GET /api/v1/auth/tokens HTTP/1.1
Host: 192.168.2.100:3128
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": 234,
    "plugin_id": "pluginAB",
    "plugin_name": "Plugin AB",
    "scopes": [
      "read",
      "control"
    ],
    "name": "Flight Controller",
    "valid_until": "2026-01-01T00:00:00.000Z",
    "created_at": "2026-01-01T00:00:00.000Z",
    "access_token": "ABCD-WXYZ-1234-5678-PQRS"
  }
]

Update plugin state

post
/v1/auth/plugin/update

Update the state of a plugin

Required scopes
This endpoint requires the following scopes:
  • : Allows sending commands to control the system.
Authorizations
OAuth2clientCredentialsRequired

Plugin authentication using Bearer token. For more details, see Fotokite API Documentation.

Token URL:
Body

Updatable fields of the plugin to report self status.

plugin_idstringOptionalDeprecated

DEPRECATED: This field is still accepted for backward compatibility but will be removed in the future.

Example: pluginAB
statestringOptionalDeprecated

DEPRECATED: Use self_status instead. This field is still accepted for backward compatibility but will be removed in the future. Possible values:

  • Disabled - Operator has not enabled this plugin yet.
  • Enabled - Operator has enabled the plugin, but there is no active session
  • Active - There is at least one session using the plugin key.
  • Connected - The plugin has reported that it is operational on any session.
  • Error - The plugin has reported an error on any session.
Example: Disabled
self_statusstringOptional

Status reported by the plugin code about itself.

  • None or <empty string> - no additional information about the plugin status is available. This is the default status.
  • Connected - the plugin is operational and connected to all required backend services.
  • Warning - a situation that requires operator attention but is not critical occurred.
  • Error - an error occurred and must be addressed by the operator.
Example: Connected
self_status_textstringOptional

Free-form status text reported by the plugin itself or by internal plugins. This is shown to the operator in the UI together with the state. There is no hard limit on the content of this field, but it is recommended to keep it concise and operator-friendly. Recommended max length is 160 characters. To reset the status text, send an empty string.

Example: Couldn't connect to back-end service. Please check your Internet connection.
Responses
204

Updated

No content
post/v1/auth/plugin/update
POST /api/v1/auth/plugin/update HTTP/1.1
Host: 192.168.2.100:3128
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 125

{
  "self_status": "Connected",
  "self_status_text": "Couldn't connect to back-end service. Please check your Internet connection."
}
No content
PreviousHealth
NextSubscription

Last updated