mirror of
https://github.com/OliveTin/OliveTin
synced 2026-08-25 03:56:33 +00:00
67 lines
3.0 KiB
Plaintext
67 lines
3.0 KiB
Plaintext
[#api-keys]
|
|
= API Keys
|
|
|
|
This page is for **developers** who want to call OliveTin's HTTP API (Connect RPC under `/api/`) using a **Bearer token**, without using the interactive web login.
|
|
|
|
API keys are configured on xref:security/local.adoc[local users] as an optional `apiKey` field. When present, clients can authenticate by sending:
|
|
|
|
----
|
|
Authorization: Bearer <your-api-key>
|
|
----
|
|
|
|
The prefix `Bearer ` (including the trailing space after `Bearer`) must match exactly.
|
|
|
|
== Configuration
|
|
|
|
include::partial$config-start.adoc[]
|
|
----
|
|
authLocalUsers:
|
|
enabled: true
|
|
users:
|
|
- username: automation
|
|
usergroup: bots
|
|
apiKey: "{{ .Env.OLIVETIN_AUTOMATION_KEY }}"
|
|
|
|
- username: alice
|
|
usergroup: admins
|
|
password: $argon2id$v=19$m=65536,t=4,p=6$...
|
|
apiKey: "{{ .Env.OLIVETIN_ALICE_API_KEY }}"
|
|
----
|
|
|
|
* Use a **long, random** API key (similar to any other bearer secret).
|
|
* Prefer loading the key from the environment with `{{ .Env.VAR }}` instead of committing the raw value to disk.
|
|
* **TLS**: send bearer tokens only over HTTPS in real deployments.
|
|
* **Interactive login**: if a user has **no** `password` configured, they **cannot** use the `/login` page; they can only authenticate with an API key (or another auth mechanism you configure separately).
|
|
|
|
Two local users **must not** share the same `apiKey` value. OliveTin will refuse to start if duplicate keys are detected.
|
|
|
|
== Authorization (permissions)
|
|
|
|
API key authentication uses the same **username** and **usergroup** as the matching local user. xref:security/acl.adoc[Access Control Lists] and `defaultPermissions` apply in the same way as for users who sign in via the web UI.
|
|
|
|
== Example: curl and Init
|
|
|
|
The OliveTin API is **Connect RPC**. Unary calls accept JSON bodies. The following example calls `Init` with an empty request object:
|
|
|
|
[source,bash]
|
|
----
|
|
curl -sS -X POST \
|
|
-H "Authorization: Bearer YOUR_API_KEY_HERE" \
|
|
-H "Content-Type: application/json" \
|
|
"https://olivetin.example.com:1337/api/olivetin.api.v1.OliveTinApiService/Init" \
|
|
--data '{}'
|
|
----
|
|
|
|
Replace the host, port, and path prefix if your installation differs. Other RPCs use the same URL pattern with a different final segment (method name).
|
|
|
|
== Operational security notes
|
|
|
|
* **Reverse proxies**: if you use xref:security/trusted_header.adoc[Trusted Header Authorization], remember it is evaluated **before** bearer API keys. Do not expose OliveTin in a way that allows clients to spoof trusted identity headers.
|
|
* **Debug logging**: avoid enabling `logDebugOptions.singleFrontendRequestHeaders` in production. OliveTin redacts common sensitive headers (including `Authorization`) in debug output, but minimizing debug surface area is still recommended.
|
|
* **Brute force**: OliveTin does not ship per-IP rate limiting for failed bearer attempts. Consider rate limiting or WAF rules on `/api/` at your reverse proxy.
|
|
|
|
== See also
|
|
|
|
* xref:security/local.adoc[Local Users Authorization] (password hashing and local user basics)
|
|
* xref:security/acl.adoc[Access Control Lists]
|