> 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/authentication-and-security.md).

# Authentication and Security

## Authentication

The authentication mechanism ensures proper security and access control. Most API endpoints are protected and scoped, meaning each request to a protected endpoint must include a valid bearer token.

### Get a token via Token Management

The simplest way to obtain a token is through our Token Management system. This method is recommended if you manage fewer than five systems.

{% stepper %}
{% step %}
Connect a computer with a web browser to the same network as your Fotokite system. We recommend using Wi-Fi.
{% endstep %}

{% step %}
Open the following URL in your browser.

```bash
http://192.168.2.100:3128/api/token_management
```

<figure><img src="/files/cVoQkoYwMN4gGJrHSaum" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Click the Create API token button to create a new token.

* Name: The name will help you organize your tokens. It will also be visible in Fotokite Live whenever your app uses that token to perform any controls.
* Scope: Token scopes determine which endpoint(s) an API token can access.
  * read: Access to all endpoints for retrieving information, except `/control` endpoints.
  * control: Access to `/control` endpoints.
  * experimental: Access to experimental and unstable features.
    {% endstep %}

{% step %}
The token (bearer token) is used to authenticate all subsequent requests to protected endpoints.

```bash
# System information
curl -X GET "http://192.168.2.100:3128/api/v0/system/info" \
--oauth2-bearer <auth_token>
```

{% endstep %}

{% step %}
Tokens can be invalidated via [Authentication](/fotokite-api/authentication.md#post-v0-auth-token-invalidate). Once a token is invalidated, you must request a new one using Token Management.

Good to know: This token does not expire.
{% endstep %}
{% endstepper %}

### Get a token via API Key

We recommend using API keys if you have more than 5 systems. Please contact Fotokite to obtain an API key.

<a href="https://fotokite.com/contact/contact-form/" class="button primary">Get API Key</a>

{% stepper %}
{% step %}
To obtain a token, send a request using [Authentication](/fotokite-api/authentication.md#post-v0-auth-token-request) by including your API Key as client\_secret.# Request token

```bash
# Request token with scopes
curl -X POST "http://192.168.2.100:3128/api/v0/auth/token/request" \
  -H "Content-Type: application/json" \
  -d '{
    "client_secret": "ApiKey123"
    "scope": "read control"
  }'
```

{% endstep %}

{% step %}
The token (bearer token) is used to authenticate all subsequent requests to protected endpoints.

```bash
# System information
curl -X GET "http://192.168.2.100:3128/api/v0/system/info" \
--oauth2-bearer <auth_token>
```

Tokens can be invalidated via [Authentication](/fotokite-api/authentication.md#post-v0-auth-token-invalidate). Once a token is invalidated, you must request a new one using your API key.

Good to know: A token generated with an API key expires after 24 hours.
{% endstep %}
{% endstepper %}

## Security

### TLS Certificates used by the Fotokite API

For use with HTTPS, the Sigma system issues certificates under the domain `*.sigma.fotokite-system.com`, for example `g2553ah.sigma.fotokite-system.com`. These certificates are signed by globally trusted certificate authorities (Google Trust Services) and assure that you are actually connected to this specific Fotokite Sigma.

However, while the certificates are globally trusted, the domain names like `g2553ah.sigma.fotokite-system.com` *do not* globally refer to the specific Sigma system and *cannot* be used to reach a Sigma system from the Internet. Instead, choose one or more of the following options to validate the certificate:

* Add a DNS override rule to your network, which maps `<gsname>.sigma.fotokite-system.com` to the IP address of the respective system. Combine this with the "NAT (Static)" setting to configure a static IP address.
* Or access the Sigma system through its assigned IP address, but instruct your TLS implementation to validate against a specific hostname, `<gsname>.sigma.fotokite-system.com`. (Refer to the provided Python code for an example).
* Or access the Sigma system through its assigned IP address, but instead of PKI validation, check the key fingerprint and compare it with a stored value (*TLS Public Key Pinning*).

#### Certificate renewal

The TLS certificates will be issued for a lifetime of 3 months and will automatically be renewed every month. The process requires that the Ground Station is powered on and connected to the internet regularly. To ensure reliable operation while completely offline, ensure that

* your client code *does not* respect certificate expiration. The Sigma system will keep using expired certificates if they can't be renewed, but your client also needs to keep accepting expired certificates.
* or your client code uses key pinning and the Sigma system is *never* connected to the internet unexpectedly. Once the system is connected to the Internet e.g. for system updates, it will renew the certificates and the pinned keys must be updated.

For best reliability and security, combine both approaches:

* When the system presents an unknown certificate in an API call, validate that it is correctly signed to a Common Name under `*.sigma.fotokite-system.com` by a public CA.
* If the certificate is valid, store it as a pinned key for this system, and keep trusting this key beyond expiration until a new, valid certificate is presented.

If you have questions regarding certificate validation or require long-lived certificates or certificates signed by specific CAs, please contact us to find a solution.


---

# 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/authentication-and-security.md?ask=<question>&goal=<endgoal>
```

`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.