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.