10. Authentication Methods Using the API
Every API of Koios Automation Platform is reached through the platform gateway, and the gateway
authenticates every request: the controller API under /api/controller/, and the gateway, EDA
and automation hub APIs under /api/gateway/, /api/eda/ and /api/galaxy/. A client
authenticates once, in one of the ways below, and the same credentials work with all of them.
10.1. Session Authentication
Sessions are what the user interface and the browsable API use. Logging in creates a session
cookie, gateway_sessionid, that the browser sends with every request until the session expires
or the user logs out.
Log in to the browsable API at https://<koios-host>/api/gateway/v1/login/. With curl, get
the csrftoken cookie first, then post the username and password with it:
curl -c cookies.txt https://<koios-host>/api/gateway/v1/login/
curl -b cookies.txt -c cookies.txt -X POST \
-H "X-CSRFToken: <csrftoken from cookies.txt>" \
--referer https://<koios-host>/api/gateway/v1/login/ \
--data-urlencode "username=<user>" --data-urlencode "password=<password>" \
https://<koios-host>/api/gateway/v1/login/
Requests that change data must also send the X-CSRFToken header. Log out with a POST to
/api/gateway/v1/logout/.
Sessions are meant for browsers. For scripts and integrations, use tokens. How long a session lasts, and how many a user may have at once, is set in Sessions and passwords.
10.2. Basic Authentication
Basic authentication sends the username and password with every request, in the Authorization
header. It needs no setup, and suits quick checks and simple scripts:
curl -u '<user>:<password>' https://<koios-host>/api/controller/v2/credentials/
It works with users whose password the gateway checks: local users, and users of LDAP, RADIUS and TACACS+ methods. Users who only log in through an SSO provider have no password the gateway can check; they use tokens.
Administrators can turn basic authentication off with Gateway Basic Auth Enabled (see Sessions and passwords). For more about the scheme, see RFC 7617.
10.3. OAuth 2 Token Authentication
Tokens are the recommended way for programs to use the API. A token is sent with each request in
the Authorization header, acts as the user who owns it, and is limited by its scope (read
or write). Tokens can be revoked at any time, and they expire.
curl -H "Authorization: Bearer <token>" https://<koios-host>/api/controller/v2/job_templates/
Create a personal token in Access Management > API Tokens, or through the API:
curl -u '<user>:<password>' -X POST -H "Content-Type: application/json" \
-d '{"description": "my script", "application": null, "scope": "write"}' \
https://<koios-host>/api/gateway/v1/tokens/
The response contains the token in its token field; it is shown only then. Applications can
also obtain tokens for users through the OAuth 2 flows at /o/. Both are described in
API tokens and OAuth applications, along with the setting that lets users from external providers create tokens.
With the token, for example, launch a job template:
curl -X POST -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
--data '{"limit": "ansible"}' \
https://<koios-host>/api/controller/v2/job_templates/14/launch/
Python example
awxkit provides the awx command line client and a Python
library for the controller API.
10.4. Single Sign-On
Users of SSO methods (SAML, OIDC, Keycloak, Azure AD, Google, GitHub) log in through their provider in the browser; the login page shows a button for each method. Unless they also have a password in a password method, they cannot use basic authentication: to call the API from a program, they use a token. See Authentication methods.