> 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/~/changes/46/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.<br>

```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"0.2.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname}:3128/api","description":"API service visible through NAT","variables":{"hostname":{"default":"sigma.local"}}}],"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. Comma-separated list.\n","allOf":[{"$ref":"#/components/schemas/Scopes"}]},"session_name":{"type":"string","description":"Name of the session for display to the operator if there can be multiple sessions per plugin.\n"}}},"Scopes":{"type":"string","description":"Available OAuth2 scopes. > - `info` - Read static information about the system. - `telemetry` - Read dynamic information about the system. - `command` - Send commands to the system. - `media` - Interaction with the media library. - `internal` - Fotokite-internal APIs. Not for third-party use."},"TokenResponse":{"type":"object","description":"OAuth2 compatible access token response.","required":["access_token","token_type","expires_in"],"properties":{"access_token":{"type":"string","description":"Token to use for future requests.\n"},"scope":{"type":"string","description":"Comma-separated list of scopes that this token grants access to.\n"},"plugin_id":{"type":"string","description":"ID of the plugin (API key) that was used to create this token.\n"},"expires_in":{"type":"integer","nullable":true,"description":"Number of seconds until this token expires and will no longer be valid.\n"},"valid_until":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when this token expires and will no longer be valid.\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":{"/v0/authentication/tokens/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/TokenResponse"}}}},"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.<br>

```json
{"openapi":"3.0.4","info":{"title":"Fotokite API","version":"0.2.0"},"servers":[{"url":"http://192.168.2.100:3128/api","description":"API service running on the system"},{"url":"http://{hostname}:3128/api","description":"API service visible through NAT","variables":{"hostname":{"default":"sigma.local"}}}],"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/v0/authentication/tokens/request","scopes":{"info":"Read static information about the system.","telemetry":"Read dynamic information about the system.","command":"Send commands to the system.","media":"Interaction with the media library.","internal":"Fotokite-internal APIs."}}}}},"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":{"/v0/authentication/tokens/invalidate":{"post":{"tags":["Authentication"],"summary":"Invalidate a token","description":"Invalidate the token used for calling the endpoint.\n","responses":{"200":{"description":"Token invalidated"},"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"}}}}}}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.fotokite.com/~/changes/46/fotokite-api/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.