> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/org/developer/oauth-applications.md).

# OAuth Applications

Create an OAuth application in your organization so MCP clients such as Claude can connect to MaiAgent MCP through OAuth authorization, without members pasting API Keys into config files; covers creat

OAuth applications let MCP clients such as Claude connect to [MaiAgent MCP](https://docs.maiagent.ai/tech/mcp/maiagent-mcp) using the standard OAuth 2.1 authorization flow. An administrator first creates an application in the organization and obtains a Client ID; a member enters the Client ID in the MCP client, signs in to MaiAgent in the browser, and clicks "Authorize" to complete the connection, without pasting an API Key into a config file.

**Differences from API Keys**:

| Item                              | OAuth application                                                                                                                                                                       | API Key                                                             |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| What the member does              | Signs in in the browser and clicks "Authorize"                                                                                                                                          | Creates a key and pastes it into the client's config file or header |
| Acts as                           | The member who completed authorization                                                                                                                                                  | The member the key is bound to                                      |
| Which organization is operated on | The organization the application belongs to                                                                                                                                             | The organization the key belongs to                                 |
| Credential validity               | Access tokens last 1 hour and the client renews them automatically; re-authorization is required if the authorization is revoked, the application is deleted, or the member is disabled | Depends on the key's expiration time                                |
| Revoking everything at once       | Delete the application, and every member's authorization becomes invalid immediately                                                                                                    | Revoke keys one by one                                              |

With both methods, the operations allowed depend on the member's own role permissions. For how to manage API Keys, see [API Key Management](https://docs.maiagent.ai/maiagent-user-guide/en/org/developer/api-keys.md).

## Who Can Use This <a href="#permissions" id="permissions"></a>

| Action                                                                                                                                                      | Required condition                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the <mark style="color:blue;">OAuth Applications</mark> page and view the application list and <mark style="color:blue;">Connection Information</mark> | Role permission <mark style="color:blue;">Organization Overview Permission</mark>                                                                                                                                                                                                                                          |
| Create, edit, and delete applications, and regenerate a Client Secret                                                                                       | "OAuth Application Management Permission" under the role permission <mark style="color:blue;">Organization Permissions</mark> (organization owners have it by default; for how to set it, see [Edit Role Permissions](https://docs.maiagent.ai/maiagent-user-guide/en/org/roles/role-permission.md#edit-role-permissions)) |
| Authorize an MCP client through an application                                                                                                              | An active member of the organization the application belongs to who can sign in to MaiAgent with a password (see [Members Who Sign In Only with SSO](#sso-only-members))                                                                                                                                                   |

Members without management permission can only view the page after entering it: the edit icon is replaced by a view (eye) icon, and the delete button cannot be clicked.

## How to Open This Page <a href="#how-to-enter" id="how-to-enter"></a>

In the left menu, click <mark style="color:blue;">Organization Settings</mark> → <mark style="color:blue;">Organization Overview</mark>, then in the <mark style="color:blue;">Management Actions</mark> area click <mark style="color:blue;">OAuth Applications</mark>.

At the top of the page is <mark style="color:blue;">Connection Information</mark>, which provides the three endpoints needed to set up an MCP client. Each one can be copied with <mark style="color:blue;">Copy</mark>:

| Endpoint                                                            | Purpose                                                                                                             |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Discovery endpoint</mark>                 | Clients that support OAuth 2.0 Authorization Server Metadata can obtain the other endpoints from here automatically |
| <mark style="color:blue;">Authorization endpoint (Authorize)</mark> | The page where members sign in and authorize                                                                        |
| <mark style="color:blue;">Token endpoint</mark>                     | Where the client exchanges and renews access tokens                                                                 |

{% hint style="info" %}
The authorization flow must use PKCE (S256); Redirect URIs are matched exactly, and wildcards are not supported.
{% endhint %}

The columns of the application list below include <mark style="color:blue;">Name</mark>, <mark style="color:blue;">Client ID</mark>, <mark style="color:blue;">Type</mark>, <mark style="color:blue;">Authorized Members</mark> (the number of members who have authorized through this application), and <mark style="color:blue;">Created At</mark>.

## Create an Application <a href="#create-application" id="create-application"></a>

1. Click <mark style="color:blue;">Create Application</mark> to open the <mark style="color:blue;">Create OAuth Application</mark> window.
2. Enter a <mark style="color:blue;">Name</mark>, for example `Claude`.
3. Select the <mark style="color:blue;">Application Type</mark> (it cannot be changed after creation; to change it, delete the application and create it again):

   | Type                                          | When to use                                                                              |
   | --------------------------------------------- | ---------------------------------------------------------------------------------------- |
   | <mark style="color:blue;">Public</mark>       | MCP clients (such as Claude); uses PKCE authorization and does not issue a Client Secret |
   | <mark style="color:blue;">Confidential</mark> | Server-side integrations; issues a Client Secret                                         |
4. Enter the <mark style="color:blue;">Redirect URIs</mark>: the URLs the flow is allowed to redirect back to after authorization, for example Claude's `https://claude.ai/api/mcp/auth_callback`. If you need multiple URLs, click <mark style="color:blue;">Add Redirect URI</mark>. Only `https://` is accepted; `http://` is allowed only for `localhost`, `127.0.0.1`, and `::1` used in local development.
5. After you confirm, the screen shows the <mark style="color:blue;">Client ID</mark>; a Confidential application also shows a <mark style="color:blue;">Client Secret</mark>.

{% hint style="warning" %}
The Client Secret is shown only this once and cannot be retrieved after you close the window. Copy and store it before clicking <mark style="color:blue;">I've saved it, close</mark>; if you forget to save it, the only option is to [regenerate the Secret](#regenerate-secret).
{% endhint %}

Each organization can create up to 20 OAuth applications. When the limit is reached, the <mark style="color:blue;">Create Application</mark> button cannot be clicked and shows the message "The organization's OAuth application limit (20) has been reached."

## Let Members Connect to MaiAgent MCP with OAuth <a href="#connect-mcp-client" id="connect-mcp-client"></a>

1. The administrator gives members the application's <mark style="color:blue;">Client ID</mark> (plus the Client Secret for Confidential applications) and the MaiAgent MCP service endpoint (see [MaiAgent MCP](https://docs.maiagent.ai/tech/mcp/maiagent-mcp#what-is-maiagent-mcp)).
2. In the MCP client, the member adds a custom connector: enter the MaiAgent MCP service endpoint as the server URL, and enter the Client ID (and Client Secret) in the OAuth settings. The client's Redirect URI must be exactly the same as the one registered in the application.
3. The client opens a browser, and the member signs in to MaiAgent with their company email and password. When the organization has LDAP credential login enabled, the password is the corporate password.
4. The authorization page shows "Authorize application name?", the account currently signed in, and the organization this application belongs to. After confirming everything is correct, click "Authorize."
5. Return to the MCP client and the connection is complete. When reconnecting later, the authorization page does not appear again as long as the authorization is still valid.

{% hint style="info" %}
When connected through OAuth, all operations apply to **the organization the application belongs to**, and the permissions are the same as the member's role permissions in that organization. If a member belongs to multiple organizations, use the application created in the organization they want to operate on.
{% endhint %}

### Members Who Sign In Only with SSO <a href="#sso-only-members" id="sso-only-members"></a>

The sign-in screen on the authorization page offers only Email and password, with no SSO sign-in button. Members who sign in only with SSO and have no MaiAgent password currently cannot complete authorization; have them connect to MaiAgent MCP with an [API Key](https://docs.maiagent.ai/maiagent-user-guide/en/org/developer/api-keys.md) instead.

## Manage Applications <a href="#manage-applications" id="manage-applications"></a>

### Edit <a href="#edit-application" id="edit-application"></a>

Click the edit icon in the list to change the <mark style="color:blue;">Name</mark> and <mark style="color:blue;">Redirect URIs</mark>; the <mark style="color:blue;">Application Type</mark> cannot be changed. The <mark style="color:blue;">Client ID</mark> is shown at the top of the window and can be copied directly.

### Regenerate Secret <a href="#regenerate-secret" id="regenerate-secret"></a>

Only Confidential applications have a Client Secret. After you click <mark style="color:blue;">Regenerate Secret</mark> in the edit window and confirm:

* The old Client Secret becomes invalid immediately; update every server-side configuration that uses it.
* Members who are already connected are not affected; only later token exchanges are affected.
* The new Client Secret is likewise shown only once.

### Delete <a href="#delete-application" id="delete-application"></a>

After you click the delete icon in the list and confirm, the tokens of every member connected through this application become invalid immediately, and this action cannot be undone. Members then need to re-authorize through a different application.

## FAQ <a href="#faq" id="faq"></a>

#### Q: The <mark style="color:blue;">Create Application</mark> button cannot be clicked? <a href="#faq-create-disabled" id="faq-create-disabled"></a>

There are two possible reasons: you do not have the "OAuth Application Management Permission" (hovering over the button shows "You do not have OAuth application management permission. Please contact your organization administrator"), or the organization already has 20 applications.

#### Q: The Redirect URI cannot be saved? <a href="#faq-redirect-uri-invalid" id="faq-redirect-uri-invalid"></a>

Only `https://` URLs are accepted; `http://` can be used only for `localhost`, `127.0.0.1`, and `::1`. The URL must exactly match the URL the MCP client actually redirects back to, including the path and port.

#### Q: After connecting, I can't find the Agent or knowledge base I expected? <a href="#faq-wrong-organization" id="faq-wrong-organization"></a>

An OAuth connection operates on the organization the application belongs to. Confirm that the Client ID the member uses comes from the correct organization, and that the member's role in that organization has permission to access those resources.

#### Q: I forgot to save the Client Secret? <a href="#faq-lost-secret" id="faq-lost-secret"></a>

The system cannot show it again. In the edit window, click <mark style="color:blue;">Regenerate Secret</mark> to get a new Secret, and update the server-side configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/org/developer/oauth-applications.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
