Skip to main content

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​

ApplicationSystem Integration
Who uses itEmployees (with their own accounts, from external tools such as Claude Code)Your company's systems
AuthenticationSign-in from an external tool (authorization code + PKCE)Service account (Client Credentials)
Where to prepareAuthorization server consoleAdmin console
APIs you can callUser APIs (conversations, organizations, projects), MCP and A2ASystem Integration API, MCP and A2A
Before using sign-in from an external tool
  • 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.

  1. Check the name of the MP realm. It is keycloak.realm_name in the installer's config.yaml (for example, agenticstar). In an installed environment, you can also get it with the following command

    curl
    kubectl get configmap librechat-auth-env -n librechat-auth -o jsonpath='{.data.KEYCLOAK_REALM}'
  2. Connect to the authorization server (if 8080 is in use, use another local port)

    curl
    kubectl port-forward -n librechat-auth svc/keycloak-extensions-keycloakx-http 8080:8080
  3. 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 are keycloak.admin_email and keycloak.admin_password in the installer's config.yaml

  4. 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.

  1. In the master realm, create a user from "Users" → "Add user", and set the password with "Set password" on the "Credentials" tab
  2. On the "Role mapping" tab, choose "Assign role", select "Filter by clients", and assign view-realm, view-clients, and manage-clients of <name of the MP realm>-realm. With only these three, the administrator can create and disable clients but cannot change the realm settings
  • The permission to manage clients is a strong one. Give it only to a limited number of 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.

StepFieldValue
General settingsClient typeOpenID Connect
Client IDThe ID to set in the external tool (for example, claude-code)
Capability configClient authenticationOff (a public client)
Standard flowOn
Direct access grantsOff
Implicit flow and OAuth 2.0 Device Authorization GrantOff
PKCE MethodS256
Login settingsValid redirect URIshttp://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 localhost and 127.0.0.1 redirect 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>/). Register http://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. Always attach this flow to external tool clients. To change the flow, see Copy and Use the Sample Flow.

3. Check the Scopes and Mappers​

  • Do not remove email on 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, remove offline_access on the "Client scopes" tab (Claude Code requests offline_access when it signs in)
  • Do not add mappers that put client_id into the token. A token with client_id is 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 Console)​

Create a service account used by your company's systems in the admin console.

  1. In the admin console, open "Users and Organizations" → "Service Accounts" and press "Create Service Account"
  2. Enter "Client ID" (letters, digits, ., _, and -), "Name", and "Description", turn on "Enabled", and create it
  3. 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 tellApplicationSystem integration
IDThe client ID of the external tool clientThe Client ID of the service account
SecretNone (a public client)Client Secret
API addresshttps://<your-domain>/api (MCP: https://<your-domain>/api/v1/mcp)The same
Where to get tokensThe external tool finds it (MCP). For your own applications, the address of the external entrance of the authorization serverhttps://<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 leakedHow to stop it
The Client Secret of a service accountIn the admin console, 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. Signing out of a device may not stop it either. It can keep refreshing its token for up to 30 days. When the user changes or resets the password, the external tool can no longer refresh its token (access tokens already issued remain usable until they expire). To stop it for certain, 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. An external tool that has already signed in also stops, and access tokens already issued can no longer be used with the external API (401, account_suspended)

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)
  • Attach to external tool clients the sign-in flow that lets through only approved users who have verified their email (Attach the sign-in flow). We recommend creating a client for each external tool and disabling clients that are no longer used

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
  • When you expose the external entrance, we recommend putting a WAF or source IP restrictions in front of it. The authorization server locks out users after repeated sign-in failures
  • 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.

ItemOn 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 mappingsCreated if missing; mappings added
The client used for sign-in to the Main Screen, and the product's service accountCreated if missing; secrets and similar aligned if present
Mappers of the client used for sign-in to the Main ScreenAdded if missing
The first administratorCreated if missing; roles and groups reattached if present
Event settings and the required event typesRestored if different; required types added if missing (types you added remain)
Passkey policy and the two required actions for passkeysRestored if different
The sample sign-in flow agentic-star browserRestored to the product's form
"Authentication flow overrides" of the built-in account, account-console, and security-admin-consoleThe sample is attached only when nothing is attached or the attached flow does not exist (a flow you attached remains)
The built-in admin-cliDisabled

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.

  1. In "Authentication" → "Flows", choose "Duplicate" from the actions of the agentic-star browser row and give it a new name
  2. In the copied flow, keep the approval check and the email check (named agentic-star browser approval and agentic-star browser email before copying)
  3. 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​