Skip to main content

Authorisations

Authorisations are used to authenticate API requests made by the agent. This is an optional setting and is only required if the API requires authentication. TootheFairyAI supports the following authorisation types:

  • API Key: This is a simple key that is passed as a query parameter in the URL.
  • Bearer Token: This is a token that is passed in the header of the request.
  • OAuth2: This is a more complex authorisation type that requires a client ID, client secret, and other parameters.
  • Password, Environment variables, Generic secret: These are other types of secrets that can be used inside execution hooks.
  • Username and password: Credentials to be used for the Desktop agents to login to web-apps and third-party applications

Authorisations can be created and or edited from the following menu: Settings > Authorisations > Create

New authorisation.

Create an authorisation​

  1. Click on the Create button.
  2. Fill in the secret name and description(optional).
  3. Select the Type from the dropdown menu (API Key, Bearer Token, OAuth2, Password, etc.).
  4. Fill in the required fields based on the secret type selected.

API Key​

For an API Key, you will need to provide the following details:

  • Key: The key that is passed as a query parameter in the URL.

Bearer Token​

For a Bearer Token, you will need to provide the following details:

  • Token: The token that is passed in the header of the request.

OAuth2​

For OAuth2, you will need to provide the following details:

  • Client ID (required): The client ID provided by the API.
  • Client Secret (required): The client secret provided by the API.
  • Authorisation URL (required): The primary token endpoint URL used to exchange credentials for an access token (e.g. https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token).
  • Token URL (optional): An alternative token endpoint URL. When provided, this takes priority over the Authorisation URL for token exchanges. Useful when the provider uses a separate endpoint for token refresh (e.g. https://identity.approvalmax.com/connect/token).
  • Grant Type (required): The grant type of the token (client_credentials or authorization_code).
  • Scope (optional): The scope of the token (e.g. https://graph.microsoft.com/.default). Not used for refresh_token exchanges.
  • Static Arguments (optional): A static set of parameters to be passed with the token request (e.g. additional form fields required by the provider).

Grant types​

client_credentials — Machine-to-machine authentication. The agent exchanges the Client ID and Client Secret directly for an access token on every API call. No user interaction required after setup.

authorization_code — User-delegated authentication. A human authorises the application once via a consent flow, and the agent uses the resulting refresh token to obtain access tokens automatically. The refresh token is rotated on each exchange and persisted securely, so the agent maintains access indefinitely as long as it runs at least once within the token's expiry window (typically 30 days).

Refresh token rotation

Some providers (e.g. ApprovalMax) issue a new refresh token on every token exchange and invalidate the previous one. ToothFairyAI handles this automatically — after each successful exchange, the new refresh token is persisted back to your stored secret. No manual intervention is needed once the initial refresh token is configured.

Initial setup for authorization_code

The first refresh token must be obtained manually by going through the provider's OAuth consent flow (authorise the app, get the code, exchange it for tokens). Once you store that initial refresh token, the agent maintains the chain automatically.

Username and Password​

For Username and Password, you will need to provide the following details:

  • Username: The username for authentication.
  • Password: The password for authentication.
  • Description: The description for the credentials - this is important as the agent will decide which credentials to use based on this description.
Note

All the secret fields are encrypted and stored securely. You will not be able to see the secret fields once you save the authorisation. In case you forget the secret fields, you will need to create a new authorisation.

Description

The description field is used by the agents to understand the purpose of the authorisation. It is not used by the system. This is extremely important for the Desktop agents and Code executioners