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.

1

Connect a computer with a web browser to the same network as your Fotokite system. We recommend using Wi-Fi.

2

Open the following URL in your browser.

http://192.168.2.100:3128/api/token_management

3

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.

4

The token (bearer token) is used to authenticate all subsequent requests to protected endpoints.

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

5

Tokens can be invalidated via Authentication. Once a token is invalidated, you must request a new one using Token Management.

Good to know: This token does not expire.

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.

Get API Key

1

To obtain a token, send a request using Authentication by including your API Key as client_secret.# Request token

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

2

The token (bearer token) is used to authenticate all subsequent requests to protected endpoints.

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

Tokens can be invalidated via Authentication. 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.

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.