> For the complete documentation index, see [llms.txt](https://developer.fotokite.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.fotokite.com/fotokite-api/authentication.md).
# Authentication
## Request a token
> 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.
```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"1.0.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname_or_ip}/api","description":"Unencrypted API anywhere, for development use","variables":{"hostname_or_ip":{"default":"localhost:3128"}}},{"url":"https://{hostname_or_ip}/api","description":"Encrypted API accessible from outside the Sigma network","variables":{"hostname_or_ip":{"default":"fotokite-sigma.local"}}},{"url":"https://{gsname}.sigma.fotokite-system.com/api","description":"Hostname used for TLS certificates. The API is not reachable there, unless a local DNS override is set.","variables":{"gsname":{"default":"G2628RH"}}}],"security":[{"ApiKeyAuth":[]},{}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"basic","description":"Provide a Fotokite API key as a HTTP basic auth password (user name is ignored).\n"}},"schemas":{"TokenRequest":{"type":"object","description":"Request to obtain a session token. Compatible with OAuth2 `client_credentials` flow.","required":["client_secret"],"properties":{"grant_type":{"type":"string","description":"OAuth2 flow type, only \"client_credentials\" is supported.\n"},"client_id":{"type":"string","description":"Ignored (For OAuth compatibility)\n"},"client_secret":{"type":"string","description":"Fotokite API key. Contact Fotokite support to get an API key assigned and activated for your systems.\n"},"scope":{"type":"string","description":"Which scopes to request access for. This must be a subset of the scopes enabled for the plugin. If more scopes are requested, the request will fail. Space separated list.\n","allOf":[{"$ref":"#/components/schemas/Scopes"}]},"token_name":{"type":"string","description":"Name of the token for display to the operator if there can be multiple sessions per plugin.\n"}}},"Scopes":{"type":"string","description":"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."},"Session":{"type":"object","description":"OAuth2 compatible access token response.","required":["id","plugin_id","scopes","access_token","created_at"],"properties":{"id":{"type":"string","description":"Unique ID of the session, used to identify the session in the system.\n"},"plugin_id":{"type":"string","description":"Unique ID of the plugin (API) key used to create this session.\n"},"plugin_name":{"type":"string","description":"Name of the plugin (API) key used to create this session.\n"},"scopes":{"type":"array","items":{"type":"string"},"description":"Scopes granted to this session token.\n"},"name":{"type":"string","description":"Name of the session for display to the operator.\n"},"valid_until":{"type":"string","format":"date-time","description":"Timestamp when this token expires and will no longer be valid.\n"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when this token was created.\n"},"access_token":{"type":"string","description":"Token to use for future requests.\n"}}},"Error":{"type":"object","description":"A generic error object.","required":["code","message"],"properties":{"code":{"description":"Unique error code.","type":"string"},"message":{"description":"User readable message of the error","type":"string"}}}}},"paths":{"/v1/auth/token/request":{"post":{"tags":["Authentication"],"summary":"Request a token","description":"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.\n","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"Token issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - API key valid but insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Invalidate a token
> Invalidate the token used for calling the endpoint.
```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"1.0.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname_or_ip}/api","description":"Unencrypted API anywhere, for development use","variables":{"hostname_or_ip":{"default":"localhost:3128"}}},{"url":"https://{hostname_or_ip}/api","description":"Encrypted API accessible from outside the Sigma network","variables":{"hostname_or_ip":{"default":"fotokite-sigma.local"}}},{"url":"https://{gsname}.sigma.fotokite-system.com/api","description":"Hostname used for TLS certificates. The API is not reachable there, unless a local DNS override is set.","variables":{"gsname":{"default":"G2628RH"}}}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"description":"Plugin authentication using Bearer token. For more details, see [Fotokite API Documentation](https://developer.fotokite.com/~/changes/46/getting-started#authentication).\n","type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"http://192.168.2.100:3128/api/v1/auth/token/request","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."}}}}},"schemas":{"Error":{"type":"object","description":"A generic error object.","required":["code","message"],"properties":{"code":{"description":"Unique error code.","type":"string"},"message":{"description":"User readable message of the error","type":"string"}}}}},"paths":{"/v1/auth/token/invalidate":{"post":{"tags":["Authentication"],"summary":"Invalidate a token","description":"Invalidate the token used for calling the endpoint.\n","responses":{"200":{"description":"Token invalidated"},"401":{"description":"Unauthorized - Invalid or missing API Token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Token valid but insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found - Specified session does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get active tokens
> Returns a list of active tokens
```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"1.0.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname_or_ip}/api","description":"Unencrypted API anywhere, for development use","variables":{"hostname_or_ip":{"default":"localhost:3128"}}},{"url":"https://{hostname_or_ip}/api","description":"Encrypted API accessible from outside the Sigma network","variables":{"hostname_or_ip":{"default":"fotokite-sigma.local"}}},{"url":"https://{gsname}.sigma.fotokite-system.com/api","description":"Hostname used for TLS certificates. The API is not reachable there, unless a local DNS override is set.","variables":{"gsname":{"default":"G2628RH"}}}],"security":[{"TokenAuth":["read"]}],"components":{"securitySchemes":{"TokenAuth":{"description":"Plugin authentication using Bearer token. For more details, see [Fotokite API Documentation](https://developer.fotokite.com/~/changes/46/getting-started#authentication).\n","type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"http://192.168.2.100:3128/api/v1/auth/token/request","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."}}}}},"schemas":{"Session":{"type":"object","description":"OAuth2 compatible access token response.","required":["id","plugin_id","scopes","access_token","created_at"],"properties":{"id":{"type":"string","description":"Unique ID of the session, used to identify the session in the system.\n"},"plugin_id":{"type":"string","description":"Unique ID of the plugin (API) key used to create this session.\n"},"plugin_name":{"type":"string","description":"Name of the plugin (API) key used to create this session.\n"},"scopes":{"type":"array","items":{"type":"string"},"description":"Scopes granted to this session token.\n"},"name":{"type":"string","description":"Name of the session for display to the operator.\n"},"valid_until":{"type":"string","format":"date-time","description":"Timestamp when this token expires and will no longer be valid.\n"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when this token was created.\n"},"access_token":{"type":"string","description":"Token to use for future requests.\n"}}},"Error":{"type":"object","description":"A generic error object.","required":["code","message"],"properties":{"code":{"description":"Unique error code.","type":"string"},"message":{"description":"User readable message of the error","type":"string"}}}},"responses":{"InternalError":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/auth/tokens":{"get":{"tags":["Authentication"],"summary":"Get active tokens","description":"Returns a list of active tokens\n","responses":{"200":{"description":"List of sessions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Session"}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - API key valid but insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## Update plugin state
> Update the state of a plugin
```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"1.0.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname_or_ip}/api","description":"Unencrypted API anywhere, for development use","variables":{"hostname_or_ip":{"default":"localhost:3128"}}},{"url":"https://{hostname_or_ip}/api","description":"Encrypted API accessible from outside the Sigma network","variables":{"hostname_or_ip":{"default":"fotokite-sigma.local"}}},{"url":"https://{gsname}.sigma.fotokite-system.com/api","description":"Hostname used for TLS certificates. The API is not reachable there, unless a local DNS override is set.","variables":{"gsname":{"default":"G2628RH"}}}],"security":[{"TokenAuth":["control"]}],"components":{"securitySchemes":{"TokenAuth":{"description":"Plugin authentication using Bearer token. For more details, see [Fotokite API Documentation](https://developer.fotokite.com/~/changes/46/getting-started#authentication).\n","type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"http://192.168.2.100:3128/api/v1/auth/token/request","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."}}}}},"schemas":{"PluginUpdatableFields":{"type":"object","description":"Updatable fields of a plugin.","properties":{"plugin_id":{"description":"Unique ID","type":"string"},"state":{"description":"Current operating state of the plugin. * `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. The first three states are determined automatically by the API service. The `Connected` and `Error` must be set explicitly by the plugin code. Plugins that are not activated for the Fotokite system in Fleet Manager will not be displayed.\n","type":"string"}}},"Error":{"type":"object","description":"A generic error object.","required":["code","message"],"properties":{"code":{"description":"Unique error code.","type":"string"},"message":{"description":"User readable message of the error","type":"string"}}}},"responses":{"InternalError":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/auth/plugin/update":{"post":{"tags":["Authentication"],"summary":"Update plugin state\n","description":"Update the state of a plugin\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginUpdatableFields"}}}},"responses":{"204":{"description":"Updated"},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - API key valid but insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found - Specified plugin does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid parameters - Request body or parameters are malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.fotokite.com/fotokite-api/authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.