API Setup Guide
How to prepare to use the Marketplace edition API. What you prepare differs between "applications", used by employees with their own accounts from external tools, and "system integrations", used by your company's systems.
Overview
| Application | System Integration | |
|---|---|---|
| Who uses it | Employees (with their own accounts, from external tools such as Claude Code) | Your company's systems |
| Authentication | Sign-in from an external tool (authorization code + PKCE) | Service account (Client Credentials) |
| Where to prepare | Authorization server console | Admin screen |
| APIs you can call | User APIs (conversations, organizations, projects) and MCP | System Integration API and MCP |
- Sign-in from an external tool is available only in environments where an administrator has opened the external entrance of the authorization server. It is closed by default. For how to open and close it, see the Domain Settings Guide in the Build section
- Each time it is opened or closed, the authorization server is replaced, and sign-in to the Main Screen and token refresh are unavailable during that time. Do it when few users are active
- To also use MCP, open the MCP inbound endpoint as well (Helm Values Reference in the Build section)
Open the Authorization Server Console
Applications are prepared in the authorization server console. The console is not exposed outside, so open it through the internal path from a terminal that can reach the cluster with kubectl.
-
Check the name of the MP realm. It is
keycloak.realm_namein the installer'sconfig.yaml(for example,agenticstar). In an installed environment, you can also get it with the following commandcurlkubectl get configmap librechat-auth-env -n librechat-auth -o jsonpath='{.data.KEYCLOAK_REALM}' -
Connect to the authorization server (if
8080is in use, use another local port)curlkubectl port-forward -n librechat-auth svc/keycloak-extensions-keycloakx-http 8080:8080 -
Open
http://localhost:8080/admin/in a browser and sign in as the administrator of the master realm. The user name and password of the first administrator arekeycloak.admin_emailandkeycloak.admin_passwordin the installer'sconfig.yaml -
Select the MP realm (the name from step 1) in the realm selector at the top left
Create an Administrator for People
The first administrator can change every realm. For everyday work, we recommend creating an administrator in the master realm who can handle only the clients of the MP realm.
- In the master realm, create a user from "Users" → "Add user", and set the password with "Set password" on the "Credentials" tab
- On the "Role mapping" tab, choose "Assign role", select "Filter by clients", and assign
view-realm,view-clients, andmanage-clientsof<name of the MP realm>-realm. With only these three, the administrator can create and disable clients but cannot change the realm settings
- People who can manage clients can create tokens impersonating other people. Give this permission only to people you trust as much as the first administrator
- Do not give console permissions to users of the MP realm (the accounts that sign in to the Main Screen)
Creating an Application (Authorization Server Console)
Create an external tool client in the MP realm. Employees set the ID of this client in their external tools and sign in.
1. Create the Client
In "Clients" → "Create client", enter the following.
| Step | Field | Value |
|---|---|---|
| General settings | Client type | OpenID Connect |
| Client ID | The ID to set in the external tool (for example, claude-code) | |
| Capability config | Client authentication | Off (a public client) |
| Standard flow | On | |
| Direct access grants | Off | |
| Implicit flow and OAuth 2.0 Device Authorization Grant | Off | |
| PKCE Method | S256 | |
| Login settings | Valid redirect URIs | http://localhost/callback and http://127.0.0.1/callback (also http://127.0.0.1/ when you use VS Code) |
- The port is not checked for the
localhostand127.0.0.1redirect URIs. You can choose any free port in the external tool (AI Client Connection Guide (MCP)) - VS Code uses the path
/for its redirect URI (http://127.0.0.1:<port>/). Registerhttp://127.0.0.1/as well when you use VS Code - Do not use Direct access grants (sending the password directly). Tokens would be issued without the approval and email checks
2. Attach the Sign-in Flow
On the "Advanced" tab of the client, in "Authentication flow overrides", select agentic-star browser for "Browser Flow" and save.
agentic-star browser is a sample sign-in flow provided by the product. As with sign-in to the Main Screen, it lets through only approved users who have verified their email. With a client that does not have this flow, users awaiting approval or with unverified email can also sign in. To change the flow, see Copy and Use the Sample Flow.
3. Check the Scopes and Mappers
- Do not remove
emailon the "Client scopes" tab. Without it, the token has no email address and calls to the external API are rejected - A long-lived token (
offline_access) can be refreshed while the user is approved, until it has been idle for up to 30 days. To stop issuing it, removeoffline_accesson the "Client scopes" tab (Claude Code requestsoffline_accesswhen it signs in) - Do not add mappers that put
client_idinto the token. A token withclient_idis treated as a system integration token
4. Check That an Account Awaiting Approval Is Rejected
Each time you create a client, sign in with a test account awaiting approval and check that it is rejected. If it can sign in, the flow in step 2 is not attached.
Clients for Regular OIDC Applications
Create clients for your own applications that are not external tools (ones that sign in with an OIDC library) in the same way, with two differences.
- Put the redirect URI of the application in "Valid redirect URIs"
- For an application that runs in the browser (one that calls the token endpoint directly from the browser), put the address of the application in "Web origins"
The sign-in flow (2), scopes (3), and check (4) are the same as for external tool clients. The endpoints of the authorization server are in Authentication API Reference — Sign-in from an External Tool.
Creating a System Integration (Admin Screen)
Create a service account used by your company's systems in the admin screen.
- In the admin screen, open "User Management" → "Service Accounts" and press "Create Service Account"
- Enter "Client ID" (letters, digits,
.,_, and-), "Name", and "Description", turn on "Enabled", and create it - On the details screen of the service account, check the Client ID and the Client Secret
For how to get a token, see Authentication Guide — Token Retrieval.
Checking the Credentials
Tell employees and the owners of the systems the following.
| What to tell | Application | System integration |
|---|---|---|
| ID | The client ID of the external tool client | The Client ID of the service account |
| Secret | None (a public client) | Client Secret |
| API address | https://<your-domain>/api (MCP: https://<your-domain>/api/v1/mcp) | The same |
| Where to get tokens | The external tool finds it (MCP). For your own applications, the address of the external entrance of the authorization server | https://<auth-domain>/api/v1/oauth/token |
<your-domain> (the domain of the external API) and <auth-domain> (the domain of the authentication service) were decided by the administrator when building the environment (Domain Settings Guide).
If Credentials Leak
| What leaked | How to stop it |
|---|---|
| The Client Secret of a service account | In the admin screen, press "Regenerate Secret" for the service account, or turn "Enabled" off. After regenerating, tokens can no longer be obtained with the previous secret |
| An employee account (sign-in from an external tool) | Stop it with the steps in "Stopping an External Tool" below |
- Access tokens already issued remain usable until they expire, even after you stop them (24 hours by default)
- Leaked credentials allow the operations permitted for that employee or service account. Data already read cannot be recovered
Stopping an External Tool
An external tool that has signed in does not stop when the user signs out of the Main Screen, changes or resets the password, or signs out of a device. It can keep refreshing its token for up to 30 days. To stop it, in the authorization server console, open the user from "Users" in the MP realm and press "Logout all sessions" on the "Sessions" tab.
- After this, the external tool can no longer refresh its token. Access tokens already issued remain usable until they expire (24 hours by default)
- A user whose approval is removed cannot sign in again. However, an external tool that has already signed in does not stop until its sessions are logged out
Notes on Applications
What External Tools Can Do
- An external tool can perform every operation permitted for the user within the APIs and MCP that the Marketplace edition offers. Token scopes do not narrow it (there are no scope restrictions)
- An approved user can get tokens not only with clients the administrator created but also with the clients for user screens that the authorization server has from the start. It is not a mechanism that limits usable external tools to the clients you created
- The "token audience check" of the MCP specification is not performed
Sign-in Screen and Protection
- The sign-in screen for external tools is the standard screen of the authorization server. It looks different from the Main Screen, and the additional protection of the Main Screen (such as one-time passwords) and the guidance to the profile settings do not apply. If you need them, configure them in the authorization server
- There is no per-IP rate limit on the external entrance (the same as the other entrances of the Main Screen). The authorization server locks users out on sign-in failures per user. To block by IP, put a WAF or similar in front of the external entrance
- In environments without a domain, the external entrance of the authorization server also uses the self-signed certificate shipped with the product, which external tools do not trust as is. Before going public, set up your own domain and a proper certificate
What the Product Creates in the Authorization Server
The following are created by the product. The settings of the MP realm are shared with the Main Screen, so changing them also affects the Main Screen. Items whose "On version upgrade" column says "Restored" return to the product's form at the next GUI version upgrade even if you change them in the console.
| Item | On version upgrade |
|---|---|
| The MP realm (display name, sign-in screen, languages, access token and sign-in session lifespans, and so on) | Set only when created (changed values remain) |
| Realm settings (password policy, lockout, client session lifespans, user name handling, SSL requirement) | Restored |
| User profile (first and last names not required; unmanaged attributes allowed) | Restored if different (other profile settings remain) |
| Roles (admin, user, developer, pending) | Created if missing |
| Groups (pending-approval, approved-users, rejected-users) and their role mappings | Created if missing; mappings added |
| The client used for sign-in to the Main Screen, and the product's service account | Created if missing; secrets and similar aligned if present |
| Mappers of the client used for sign-in to the Main Screen | Added if missing |
| The first administrator | Created if missing; roles and groups reattached if present |
| Event settings and the required event types | Restored if different; required types added if missing (types you added remain) |
| Passkey policy and the two required actions for passkeys | Restored if different |
| The sample sign-in flow agentic-star browser | Restored to the product's form |
| "Authentication flow overrides" of the built-in account, account-console, and security-admin-console | The sample is attached only when nothing is attached or the attached flow does not exist (a flow you attached remains) |
| The built-in admin-cli | Disabled |
New items created by the product (the sample sign-in flow and its conditions) have names starting with agentic-star, and their description fields say that they belong to the product.
Copy and Use the Sample Flow
agentic-star browser returns to the product's form at version upgrades, so do not change it directly. To change it, copy it.
- In "Authentication" → "Flows", choose "Duplicate" from the actions of the
agentic-star browserrow and give it a new name - In the copied flow, keep the approval check and the email check (named
agentic-star browser approvalandagentic-star browser emailbefore copying) - In "Authentication flow overrides" of your clients, select the copied flow for "Browser Flow"
The copied flow is yours and is not touched by version upgrades. When the product's sample changes in a version upgrade, copy it again and reapply your changes.
Next Steps
- AI Client Connection Guide (MCP) — Configuring external tools and signing in
- Authentication Guide — How to get tokens
- Call the API — The shortest steps to call the Chat API with a system integration