Use Your Own OAuth App
Sign people in to your own API through your OAuth app, or let Fruxon sign in as the app
A custom integration can authenticate through an OAuth app you own: one registered at your identity server (Auth0, Okta, Microsoft Entra ID, Keycloak, Google, GitHub, or any server that speaks OAuth 2.0). The app's client ID and secret are entered once, on the integration, and every config of that integration uses them.
The method has two ways to get a token. Pick one under Who signs in:
| Who signs in | What happens | Use it when |
|---|---|---|
| People sign in (authorization code) | Someone connects an account through your sign-in page, and tools act as that account. | The API acts on behalf of a person: their mailbox, their records, what they're allowed to see. |
| Fruxon signs in as the app (client credentials) | Fruxon gets a token with the client ID and secret whenever a tool runs. Nobody connects anything. | A server-to-server API that trusts the app itself (Auth0 and Okta machine-to-machine apps, Entra app registrations, Keycloak service accounts). |
With Fruxon signs in as the app, the token is the app's. Every person who talks to an agent using it acts as the app, with all of the app's permissions. Grant the app only what every one of those people may do, or use People sign in instead.
Add the method
- Open the integration and choose Edit integration.
- Choose Add auth method and set Type to OAuth app.
- Pick Who signs in, then fill in the fields below.
- Save the integration, then create a config for it.
The Client secret is stored encrypted and never shown again after you save. To keep it, leave the field blank when you edit the method later. Fruxon only ever sends it to the token URL and the revocation URL. If you change either URL, enter the secret again, so that a changed address can't receive a secret saved for a different one.
People sign in
Register the app at your identity server first. Fruxon needs these settings from it:
| Field | What to enter |
|---|---|
| Redirect URI | Shown by Fruxon, with a copy button. Register this exact address on your OAuth app as an allowed redirect URI. |
| Authorization URL | Where people are sent to sign in and approve access, such as https://id.example.com/oauth/authorize. Must be https://. |
| Token URL | Where Fruxon exchanges the sign-in for tokens and refreshes them, such as https://id.example.com/oauth/token. Must be https://. |
| Client ID | The app's client ID. It stays readable, so you can compare it with your identity server. |
| Client secret | The app's secret. Optional with PKCE: leave it blank if your app is a public client with no secret. |
| Use PKCE | On by default for a new method. It adds a PKCE (S256) challenge to each sign-in. Leave it on unless your identity server rejects it. An app without a client secret needs it. |
| Scopes | Requested every time someone connects. Type a scope and press Enter. |
Under More options:
| Field | What it does |
|---|---|
| Sign-in parameters | Extra parameters added to the sign-in address, such as audience or prompt. |
| Token request parameters | Extra fields sent with every token request (the code exchange and each refresh), such as audience or resource. They can't replace the fields Fruxon sends itself. |
| Client authentication | How the client ID and secret reach the token URL: in the request body, or as HTTP Basic. An app without a secret always sends just its ID in the body. |
| Revocation URL | Optional. Where a connection's tokens are revoked when it ends (RFC 7009). See When a connection ends. |
| Token header / Token scheme | How tools send the token. Blank means Authorization: Bearer <token>. |
Connecting
The config's credential level decides who connects:
- Application-level: an admin connects one account on the config page, and every agent using the config acts as it.
- User-level or User-level + shared fallback: each person connects their own account the first time an agent needs it, from a link the agent sends. With the fallback, calls use the admin's account until the person connects theirs.
At the user levels, an admin can also limit how long each person's connection is kept. See How long connections are kept.
Asking for no refresh token
A refresh token lets Fruxon keep a connection alive without asking the person again. If you don't want one issued at all, don't ask your identity server for it:
- OpenID Connect servers (Auth0, Okta, Entra ID, Keycloak): leave
offline_accessout of Scopes. - Google: don't add
access_type=offlineto Sign-in parameters.
If your server issues one anyway, turn on Don't keep a refresh token on the config. Fruxon then throws the refresh token away before storing the connection. See How long connections are kept.
Fruxon signs in as the app
| Field | What to enter |
|---|---|
| Token URL | Where Fruxon asks for the app's token. Must be https://. |
| Client ID | The app's client ID. |
| Client secret | Required. |
| Scopes | Sent as scope with every token request. |
| Token request parameters (under More options) | Extra fields such as audience (Auth0) or resource. |
A config for this method is always Application-level: there is no account to connect, so the config page has no Connect button. Choose Test instead. Fruxon gets a token, and if the method has a Verification endpoint, it calls that endpoint with the token.
Fruxon keeps the token in memory until shortly before it expires, then gets a new one. Nothing is stored. Editing the method's settings always gets a new token. A token your identity server revokes early is still used until it expires.
Examples
Auth0 (machine-to-machine application):
| Field | Value |
|---|---|
| Token URL | https://<your-domain>.auth0.com/oauth/token |
| Token request parameters | audience = your API's identifier |
Microsoft Entra ID (app registration with application permissions):
| Field | Value |
|---|---|
| Token URL | https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token |
| Scopes | https://graph.microsoft.com/.default |
For Entra, grant the app registration the Microsoft Graph application permissions the tools need, and have an admin grant consent for the tenant.
From the CLI
fruxon integrations create --file and update --file accept the same method as JSON (type: "O_AUTH2"). Leave the client secret out of the file and enter it in the console, so it never sits on disk. A method that signs in as the app has nothing to connect, so fruxon integrations connect refuses it. Check it with Test, or with fruxon integrations verify <integration> --file <auth.json>. See CLI.