Skip to main content


By default, authentication is disabled. There are two ways of protecting resources from unauthorized access. You can set security.systemToken in the cluster configuration to a secure secret value in your airy.yaml and apply it. Once that is done you authenticate by setting the token as a value on the Bearer Authorization header when making requests.

This is fine for API only access, but it means that UI clients will no longer work since api keys are not meant for web authentication. Therefore Airy Core also supports Open Id Connect (OIDC) to allow your agents to authenticate via an external provider. If you configure this in addition to the system token then both types of authentication will work when requesting APIs. If you only configure OIDC authentication then regular

Configuring OIDC#

OIDC is an authentication layer on top of the popular OAuth 2.0 authorization framework. With the added information of "who" made a request (authentication) Airy Core is able to offer audit and workflow features.


The easiest way to configure our OIDC is by using our GitHub preset. We will explain how to configure any OIDC provider further below. To get started you first need a GitHub OAuth app. You can follow this guide and as an Authorization Callback URL you need to put your Airy host with the path /login/oauth2/code/github. So if your Airy Core instance is hosted at the Callback URL would be


You can always get your Airy host by running the CLI command airy api endpoint

Now you can add your GitHub app configuration to the security section in your airy.yaml:

allowedEmailPatterns: "*,"
provider: "github"
clientId: "github oauth client id"
clientSecret: "github oauth client secret"

Since you don't want just any GitHub user to be able to access your Airy Core instance you are also required to add a list of emails or email wildcard patterns to define which users are authorized for use.

Once this configuration is applied all new requests to the Airy Core API will be redirected to the Github provider for login. If that login is successful the Airy Core platform will set a http only authentication cookie that will authenticate the current user session.

Any open id provider#

To configure any open id connect provider for authentication we expose the following configuration values:

allowedEmailPatterns: ""
provider: "my-provider"
clientId: "client-id"
clientSecret: "client-secret"
scope: "openid,email" # comma separated list of scopes. Must include "openid"
clientAuthenticationMethod: "basic" # One of [basic,post,none]
authorizationGrantType: "authorization_code" # One of [authorization_code,implicit,refresh_token,client_credentials,password]
authorizationUri: ""
tokenUri: ""
userInfoUri: ""
userInfoAuthenticationMethod: "form" # One of [header,form,query]
userNameAttributeName: "id" # Field name within the OIDC identity token that uniquely identifies the user
issuerUri: ""
jwkSetUri: ""

The redirect Uri to configure with your provider will always be of the form {airy core host}/login/oauth2/code/{provider name}.

Last updated on