Skip to content

Authentication

To authenticate with AI-on-Demand, you need an account. First navigate to the web portal and click login, you can choose to use any authentication service and an account will be created automatically.

Never code your keys into a script

There is never a reason you should include your refresh token or client secret in a script directly. If you do, you may end up accidentally sharing your secrets when you share it with a colleague or in a public repository.

Instead, you can use the built-in functionality to write or read tokens from file. Alternatively, you can use solutions such as python-dotenv to use .env files which can be easily overriden with environment variables.

User Authentication Flow Example

Initiate the authentication process by calling aiod.create_token. Specifying write_to_file=True will ensure the obtained token is stored at ~/.aiod/token.toml and can be used in subsequent Python sessions.

Initiate Authentication
import aiod
aiod.create_token(write_to_file=True)
The above command will output instructions to console on how to obtain a valid token, e.g.:

Instructions in the Console
Please authenticate using one of two methods:

  1. Navigate to https://auth.aiod.eu/aiod-auth/realms/aiod/device?user_code=ACBC-ARFZ
  2. Navigate to https://auth.aiod.eu/aiod-auth/realms/aiod/device and enter code ACBC-ARFZ

This workflow will automatically abort after 300 seconds.

This function will block until timeout_seconds have elapsed, or the instructions have been followed successfully. After authentication, you can do authenticated requests, such as getting information about the logged in user:

aiod.get_current_user()
# returns: User(name='...', roles=('...', ...))

Bot Authentication Flow Example

In some rare cases, you may want to have a dedicated bot account. This is not for regular users, but may be granted to organisations to, for example:

  • Allow the creation of a connector which automatically syncs metadata from their platforms to AI-on-Demand (such as the OpenML connector)
  • The development of AI-on-Demand internal services which integrate through the REST API and need to perform certain authenticated requests.
Do I need this?

If you need to ask, then the answer is probably no. Use the user login flow described above.

If you want to obtain a client_id and client_secret, please reach out with a motivation on why you need it, what you will use it for, and why the user authentication flow is not sufficient. With a client_id and client_secret, you can use that to authenticate as follows:

secret.toml
client_secret = "S2zo0zW6QMy8ffcqCozYbHkj0JajcWtQ"

from pathlib import Path
import aiod

aiod.config.client_id = CLIENT_ID
token = aiod.authentication.Token.from_file(Path("secret.toml"))
# or:
# token = aiod.authentication.Token(client_secret=...)
aiod.authentication.set_token(token)

Authentication Reference

AuthenticationError

Bases: builtins.Exception

Raised when an authentication error occurred.

NotAuthenticatedError

Bases: builtins.Exception

Raised when an endpoint that requires authentication is called without authentication.

Token

Ensures active access tokens provided through one dedicated refresh token.

has_expired property

Return whether the access token has expired based on local data.

headers property

HTTP authorization header data for the token.

Examples:

import aiod
token = aiod.get_token()
requests.post(url, headers=token.headers, json=metadata)

create_token

Get an API Key by prompting the user to log in through a browser.

Notes

This is a blocking function, and will poll the authentication server until authentication is completed or timeout_seconds have passed.

Parameters:

Name Type Description Default
timeout_seconds int

The maximum time this function blocks waiting for the authentication workflow to complete. If timeout_seconds seconds have elapsed without successful authentication, this function raises an AuthenticationError. This must be set to a positive integer.

 300
write_to_file bool

If set to true, the new api key (refresh token) will automatically be saved to the user configuration file (~/.aiod/config.toml).

 False
use_in_requests bool

If set to true, the new token will automatically be used for future authenticated requests.

 True

Returns:

Type Description
Token

The new token for use in authenticated requests.

Raises:

Type Description
AuthenticationError

If authentication is unsuccessful in any way.

get_current_user

Return name and roles of the user that is currently authenticated.

Returns:

Type Description
User

The user information for the currently authenticated user.

Raises:

Type Description
NotAuthenticatedError

When the user is not authenticated.

get_token

Get the currently configured token that is used for authenticated requests.

Returns:

Type Description
Token

invalidate_token

Invalidates the current (or provided) API key.

Ends the current keycloak session, invalidating all keys issued.

Parameters:

Name Type Description Default
token str | Token | None

The token to invalidate. If str, it should be a refresh token. If None, it will default to the currently configured token.

 None
ignore_errors bool

If true, do not raise an error if the logout attempt failed.

 False

set_token

Set the token directly.

Parameters:

Name Type Description Default
token Token

Sets the token to be used for authenticated requests.

 required
Notes

This function does not validate the provided token. If the token is invalid, subsequent authenticated requests may fail.