Skip to content

OAuth2 Get Token – fetching an access token for an API call

The command "OAuth2 Get Token" asks the token endpoint of an OAuth2 provider (for example Microsoft Entra ID, Auth0, Keycloak) for an access token and writes it into variables. This page is for administrators who call APIs that are protected with OAuth2.

1. At a glance
Purpose Obtain an access token that a following HTTP Request sends in its Authorization header
Typical use Server-to-server calls with the client credentials grant; renewing a user's token with a refresh token
Where in the editor Toolbar menu "Communication" → "OAuth2 Get Token"
Needs a user interface No – works in scheduled actions, background rules and REST API calls
Related OAuth2 User Authorization, HTTP Request

Summary

  • The command only fetches the token. It does not call the target API.
  • A failed token request does not stop the action. Check "Has Error Variable" before you use the token.
  • With "Cache Token" on, a valid token is reused instead of being fetched on every run.
  • For a token that represents the signed-in user – with a sign-in window of the provider – use OAuth2 User Authorization.

2. Settings

"Display Name", "Description" and "Execution Condition" are on the tab "General" (see Actions). All text settings are expressions.

Tab "Token Request"

Setting Meaning Default / Required
"Token Endpoint" Address of the token endpoint, for example https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token Required
"Grant Type" How the token is requested (see below) ClientCredentials
"Scope" Scopes, separated by spaces. Entra ID expects <resource>/.default for client credentials. Empty: the provider decides
"Cache Token" Keeps the token and reuses it while it is valid (section 3) Off
"Ignore Certificate Errors" Accepts an invalid TLS certificate of the token endpoint Off

Tab "Client"

Setting Meaning Default / Required
"Client Id" The ID the application is registered under at the provider Required
"Client Secret" The secret of the client. Empty for a public client without secret. Empty
"Client Authentication" How client ID and secret are sent (see below) BasicAuthenticationHeader

Tab "Grant"

Each grant type reads only the values it needs; the others are kept but ignored.

Setting Used by grant type Meaning
"User Name", "Password" PasswordCredentials User name (required) and password
"Authorization Code" AuthorizationCode The code to exchange (required). A code is valid only once and only for minutes.
"Redirect Address" AuthorizationCode The redirect address the code was requested with – exactly the same text
"PKCE Code Verifier" AuthorizationCode The PKCE verifier the code was requested with; empty without PKCE
"Refresh Token" RefreshToken The refresh token to exchange (required)

Tab "Additional Parameters"

The plus button adds a parameter with "Name" and "Value", for parameters a provider requires beyond the OAuth2 standard – for example audience for Auth0 or resource for older Entra ID endpoints. A parameter whose name is empty is left out; an empty value is sent as an empty parameter.

Tab "Response"

Setting Receives
"Access Token Variable" The access token – the value for the header Authorization: Bearer <token>
"Token Type Variable" The token type, normally Bearer
"Expires In Variable" The lifetime of the token in seconds
"Refresh Token Variable" The refresh token, if the provider returns one; otherwise empty
"Id Token Variable" The ID token of an OpenID Connect provider (when the scope openid was requested)
"Response Body Variable" The complete answer of the endpoint as text – read it when something failed
"Response Code Variable" The HTTP status code of the token request
"Has Error Variable" true when no token was obtained, otherwise false
"Error Variable" The reason – error and error_description of the provider, or the technical reason

Set at least one of "Access Token Variable", "Refresh Token Variable", "Id Token Variable" or "Response Body Variable" – otherwise the token is lost.

Grant types

Value When to use it
ClientCredentials The application signs in as itself. The token carries the permissions of the application, not of a person. The usual choice for server-to-server calls.
PasswordCredentials User name and password are sent to the provider. Discouraged by the OAuth2 security recommendations and refused by many providers – only for a legacy endpoint that offers nothing else.
AuthorizationCode Exchanges a code that was obtained before, for example through a sign-in window.
RefreshToken Exchanges a refresh token for a new access token without asking the user again.

Client authentication

Value What is sent
BasicAuthenticationHeader Client ID and secret as HTTP Basic authentication header – the standard way, expected by most providers
RequestBody client_id and client_secret in the form body
ClientIdOnly Only the client ID, in the form body – for a public client

If the provider answers invalid_client, try the other way of sending the client data first.

3. Behaviour

  1. The expressions are evaluated.
  2. If "Token Endpoint" is empty or not an absolute http/https address, if "Client Id" is empty, or if the chosen grant type misses its required value, no request is sent; "Has Error Variable" is true and "Error Variable" names what is missing.
  3. A "Client Secret" that is configured but evaluates to empty (for example a missing global value) is noted in the log; only the client ID is sent.
  4. The token request is sent as a form POST. The answer is written into the response variables.
  5. A refusal by the provider or a connection failure sets "Has Error Variable" to true and writes the reason. The action continues.

Cache Token

With "Cache Token" on:

Situation What happens
A stored token is still valid for more than 2 minutes It is used; the provider is not asked
The stored token has expired and a refresh token is stored The token is refreshed silently and stored again
The refresh is refused, or nothing is stored A new token is requested as configured
Client secret, scope or endpoint were changed The stored token is no longer used

Who shares a stored token: a token of the grant type ClientCredentials belongs to the application and is shared by everybody who runs the action. A token of every other grant type represents a person and is stored per user; if the user cannot be determined, nothing is cached.

Stored tokens are kept encrypted in the database. The key is the data protection key of the installation: without DataProtection:KeyRingPath, stored tokens cannot be read after a restart and are fetched again (see Installation and configuration).

Switch the cache on for actions that run often – token endpoints limit the number of requests like any other API.

4. Examples

Call Microsoft Graph as the application.

  1. "OAuth2 Get Token"
    • "Token Endpoint" https://login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token
    • "Grant Type" ClientCredentials, "Scope" https://graph.microsoft.com/.default
    • "Client Id" and "Client Secret" from global values
    • "Cache Token" on
    • "Access Token Variable" Token, "Has Error Variable" TokenFailed, "Error Variable" TokenError
  2. HTTP Request with header Authorization = Bearer followed by Token, and the "Execution Condition" TokenFailed is false.

Renew a user's token. After OAuth2 User Authorization has stored a refresh token in a variable, "OAuth2 Get Token" with "Grant Type" RefreshToken and "Refresh Token" = that variable returns a new access token.

5. Limitations

  • Client secrets and passwords are expressions of the action or of global values and are stored readable. Keep them in one place, such as a global value, and grant the permissions to change actions and global values to few people (see API access and credentials). OAuth2 settings cannot be kept in a credentials definition.
  • There is no command to discard a stored token by hand. Changing the client secret, the scope or the endpoint makes the command request a new one.
  • Two runs that refresh the same expired token at the same moment can invalidate each other's refresh token at providers that rotate refresh tokens. The next run then requests a new token.
  • "Ignore Certificate Errors" sends the client secret to a server whose identity is not checked. Use it only for test systems.