> ## Documentation Index
> Fetch the complete documentation index at: https://app.miyon.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth providers (JWT)

> JWT OAuth authentication for external APIs -- Google, Microsoft, and TKP.

## What is a JWT OAuth provider?

A **JWT OAuth provider** lets your AI assistant authenticate automatically against external APIs. Instead of using static API keys, a signed JWT (JSON Web Token) is created and exchanged for a short-lived access token. Expired tokens are renewed automatically.

> [!NOTE]
>
> **Security:** All stored credentials (private keys, tokens) are stored encrypted and are only accessible to your account.

**Typical use cases:**

* Google Cloud APIs (e.g. Google Calendar, Google Sheets)
* Microsoft Graph API (e.g. Outlook, Teams)
* TKP / soft-nrg workshop planning system

## Where do I find the OAuth providers?

1. Click your **Account** in the bottom left
2. Select **OAuth providers**

There you see a list of all configured OAuth providers and can create new ones.

## Where is the OAuth provider used?

### In the API tool

When creating or editing an **API tool**, you will find the dropdown **"Link OAuth provider (optional)"**. Here you can select a previously created OAuth provider. The AI assistant then automatically uses a valid access token for every API call and renews it on its own as soon as it expires.

Below the dropdown you will find the link **"+ Create new OAuth provider"**, which opens the OAuth provider management in a new tab.

### In the TKP integration

When configuring the **TKP integration** (workshop appointments), a JWT OAuth provider is required. Select the matching provider from the dropdown.

## Create a new JWT OAuth provider

1. Open the **OAuth providers** page
2. Click the dropdown **"Create new OAuth provider"**
3. Select **"JWT OAuth"**
4. Optional: choose a **Quick Start template** (Google, Microsoft, or TKP)
5. Fill in the remaining fields
6. Test the connection
7. Click **Save**

## Quick Start templates

When creating a new JWT OAuth provider, three preconfigured templates are available. They fill in most fields automatically -- you only need to enter your individual credentials.

| Quick Start | Description | What gets filled in? |
| - | - | - |
| **Google** | For Google Cloud APIs (Calendar, Sheets, etc.) | Token URL, algorithm, lifetime, audience, grant type |
| **Microsoft** | For Microsoft Graph / Azure AD | Token URL, algorithm, lifetime, audience, grant type, client assertion type |
| **TKP** | For the soft-nrg workshop planning system | Token URL, algorithm, lifetime, audience, scope, grant type |

> [!NOTE]
>
> **Note:** Quick Start templates are only available when creating new providers (not when editing). Sensitive data you have already entered (private key, issuer) is preserved when switching templates.

## Form fields in detail

### Basic settings

| Field | Description | Required |
| - | - | - |
| **Name** | Descriptive name (e.g. "Google Calendar Prod") | Yes |
| **Token URL** | OAuth token endpoint URL (HTTPS only) | Yes |

### JWT signing

| Field | Description | Default |
| - | - | - |
| **Algorithm** | RS256, RS384, RS512, ES256, ES384, ES512 | RS256 |
| **JWT lifetime** | Validity of the JWT in seconds | 300 |
| **Key ID** | Optional key ID for the JWT header ("kid") | -- |
| **Private key (PEM)** | Your RSA or ECDSA key in PEM format | Required |

### JWT claims (payload)

| Field | Description | Required |
| - | - | - |
| **Issuer (iss)** | Sender -- usually the client ID or service account email | Yes |
| **Subject (sub)** | Subject -- for Microsoft, the issuer is used when empty | No |
| **Audience (aud)** | Recipient -- usually the token URL | Yes |
| **Scope** | OAuth permissions, separated by spaces | No |

### Response format

| Field | Description | Default |
| - | - | - |
| **Token field name** | JSON field containing the access token | access\_token |
| **Expires-in field name** | JSON field containing the token validity | expires\_in |
| **Grant type** | OAuth 2.0 grant type | depends on template |

### Advanced options

| Field | Description |
| - | - |
| **Header extras** | Additional JWT header fields as JSON (e.g. `{"x5t":"..."}`) |
| **Extra token request params** | Additional parameters for the token request as JSON |
| **JWT assertion field name** | Field name for the JWT assertion in the POST body |
| **Client assertion type** | Type of the client assertion (for Microsoft) |
| **Send scope in POST body** | Required for certain client assertion flows (e.g. Microsoft) |

## Example: TKP workshop planning

> [!TIP]
>
> **Quick Start:** Click **TKP** -- most fields are filled in automatically.

**Automatically filled fields:**

* **Token URL:** `https://auth.soft-nrg.com/oauth/token`
* **Algorithm:** RS256
* **JWT lifetime:** 300 seconds
* **Audience:** `https://auth.soft-nrg.com/oauth/token`
* **Scope:** `scope.api.planning.extendedplan`
* **Grant type:** `urn:ietf:params:oauth:grant-type:jwt-bearer`

**What you still need to enter:**

1. **Name** -- e.g. "TKP Werkstatt Prod"
2. **Private key** -- your RSA private key in PEM format (provided by soft-nrg)
3. **Key ID** -- your key ID from soft-nrg (if available)
4. **Issuer (iss)** -- your client ID from soft-nrg
5. **Subject (sub)** -- if specified by soft-nrg

**Usage:** Afterwards, link the created provider in the **TKP integration**.

## Example: Google Cloud API

> [!TIP]
>
> **Quick Start:** Click **Google** -- most fields are filled in automatically.

**Automatically filled fields:**

* **Token URL:** `https://oauth2.googleapis.com/token`
* **Algorithm:** RS256
* **JWT lifetime:** 3600 seconds (1 hour)
* **Audience:** `https://oauth2.googleapis.com/token`
* **Grant type:** `urn:ietf:params:oauth:grant-type:jwt-bearer`

**What you still need to enter:**

1. **Name** -- e.g. "Google Calendar Prod"
2. **Private key** -- from the Google Cloud service account JSON file (field `private_key`)
3. **Key ID** -- from the JSON file (field `private_key_id`), if available
4. **Issuer (iss)** -- the service account email (e.g. `mein-service@projekt.iam.gserviceaccount.com`)
5. **Subject (sub)** -- the email of the user on whose behalf the assistant acts (with domain-wide delegation)
6. **Scope** -- the required permissions, e.g.:
   * Google Calendar: `https://www.googleapis.com/auth/calendar`
   * Google Sheets: `https://www.googleapis.com/auth/spreadsheets`

**Usage:** Link the created provider in the **API tool** that calls the Google API.

## Example: Microsoft Graph API

> [!TIP]
>
> **Quick Start:** Click **Microsoft** -- most fields are filled in automatically.

**Automatically filled fields:**

* **Token URL:** `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`
* **Algorithm:** RS256
* **JWT lifetime:** 600 seconds (10 minutes)
* **Audience:** `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`
* **Grant type:** `client_credentials`
* **Client assertion type:** `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
* **Send scope in POST body:** Enabled

> [!WARNING]
>
> **Important:** Replace `{tenant}` in the token URL and audience with your Azure tenant ID!

**What you still need to enter:**

1. **Name** -- e.g. "Microsoft Graph Prod"
2. **Token URL** -- replace `{tenant}` with your Azure tenant ID
3. **Audience** -- replace `{tenant}` with your Azure tenant ID
4. **Private key** -- your certificate's private key in PEM format
5. **Key ID** -- the thumbprint of your certificate
6. **Issuer (iss)** -- your Azure application (client) ID
7. **Subject (sub)** -- your Azure application (client) ID (identical to the issuer for Microsoft)
8. **Scope** -- e.g. `https://graph.microsoft.com/.default`
9. **Header extras** (optional) -- `{"x5t":"YOUR_CERTIFICATE_THUMBPRINT"}` (hex values are automatically converted to Base64url)

**Usage:** Link the created provider in the **API tool** that calls the Microsoft Graph API.

## Test the connection

After filling in the form, you can test the connection **before** saving the provider:

1. Click **Test connection**
2. The system creates a JWT and exchanges it for an access token
3. On success, the received token is displayed
4. On failure, the OAuth server's error message is displayed

> [!NOTE]
>
> **Tip:** You can also test the connection without saving the provider. This lets you try out different configurations.

## Common errors

| Error | Cause | Solution |
| - | - | - |
| **Invalid key format** | Private key is not in PEM format | Make sure the key starts with `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN PRIVATE KEY-----` |
| **Token request failed** | Wrong token URL or credentials | Check the token URL, issuer, and private key |
| **Invalid audience** | Audience does not match the expected value | Check the audience -- it is usually the token URL itself |
| **Scope not permitted** | Missing permissions | Make sure the service account has the required permissions |
| **{tenant} in URL** | Placeholder not replaced | Replace `{tenant}` with your actual Azure tenant ID |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.