Skip to main content

OAuth Authentication for Client API

OAuth is the recommended authentication method for Client API integrations. You authenticate with an OAuth access token instead of managing a Glean-issued API token.

There are two sources for that token, and they behave slightly differently on the wire:

Glean OAuth Authorization Server

Glean issues the tokens (OAuth 2.1)

External Identity Provider

Your IdP issues the tokens

  • Google, Okta, Azure Entra ID, OneLogin, etc.
  • Token lifecycle owned by your IdP
  • Requires the X-Glean-Auth-Type: OAUTH header
  • Reuses your existing enterprise auth
warning

OAuth is supported for the Client API only. Indexing API operations require Glean-issued tokens and do not accept OAuth.

Authentication Headers​

Every OAuth request sends the access token as a bearer credential:

Authorization: Bearer <oauth_access_token>

Whether you also need X-Glean-Auth-Type: OAUTH depends on who issued the token:

Token sourceX-Glean-Auth-Type: OAUTH
Glean OAuth Authorization Server (incl. Dynamic Client Registration)Not required — Glean recognizes its own tokens by their issuer
External identity provider (Google, Okta, Azure, etc.)Required — without it the token is treated as a Glean API token and rejected with 401
Using an SDK?

The official API clients accept an OAuth access token in their existing token field. See the OAuth section of the TypeScript, Python, Go, or Java client docs.

Setup​

The Glean OAuth Authorization Server is an OAuth 2.1 authorization server that issues access tokens for the Client API. It reuses your existing SSO for user authentication — it does not replace your IdP.

1

Enable the authorization server

The Glean OAuth Authorization Server is disabled by default. An administrator enables it in the Glean admin console.

2

Register a client

Register a static client, or allow Dynamic Client Registration (primarily for MCP hosts). Administrators can restrict or disable dynamic registration.

3

Obtain a token

Use the Authorization Code flow with PKCE. Discover endpoints from the server metadata document and exchange the authorization code for an access token.

Endpoints (replace <instance> — see finding your server URL):

PurposeURL
OAuth server metadatahttps://<instance>-be.glean.com/.well-known/oauth-authorization-server
Tokenhttps://<instance>-be.glean.com/oauth/token
Dynamic Client Registrationhttps://<instance>-be.glean.com/oauth/register

The metadata document is the authoritative source for endpoints — fetch it to discover the current authorization, token, registration, and any other endpoints rather than relying on the values listed above.

Tokens from the Glean Authorization Server are recognized by their issuer, so requests do not need the X-Glean-Auth-Type header.

Implementation Examples​

curl -X POST https://<instance>-be.glean.com/rest/api/v1/search \
  -H 'Authorization: Bearer <oauth_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "quarterly reports",
    "pageSize": 10
  }'

Token Properties​

  • Scope: Governed by Glean scopes (for example SEARCH, CHAT). For static clients, the allowed scopes are selected when the client is created or edited; dynamically registered (DCR) clients are limited to a restricted subset. Request only the scopes your integration needs
  • User context: Treated as user-permissioned; permissions are enforced by Glean at request time
  • Expiration & refresh: Controlled by the issuer (Glean Authorization Server or your IdP). For a refresh token, request the offline_access scope and refresh with a standard OAuth library
  • API support: Client API only (Indexing API not supported)

Troubleshooting OAuth​

ErrorCauseSolution
401 Unauthorized / Invalid SecretExternal-IdP token sent without X-Glean-Auth-Type: OAUTH, so it was treated as a Glean API tokenAdd the X-Glean-Auth-Type: OAUTH header (external-IdP tokens only)
401 UnauthorizedInvalid or expired tokenVerify the token is valid and not expired; refresh if needed
403 ForbiddenOAuth not enabled, or client ID / issuer mismatchConfirm OAuth is enabled in Glean and the registered client ID / issuer matches the token
Invalid token formatMalformed tokenVerify the token is a valid JWT from your issuer
note

If you are using the Glean OAuth Authorization Server and still see a missing-header error, confirm the token was issued by Glean's server (not your IdP). Glean-issued tokens are detected by issuer and need no header; external-IdP tokens always do.

Best Practices​

Security​

  • Use HTTPS for all OAuth flows and API requests
  • Use Authorization Code + PKCE — it is required by OAuth 2.1 and by the Glean Authorization Server
  • Store tokens securely — never commit them to version control
  • Handle token refresh gracefully using a standard OAuth library

Production​

  • Use production OAuth applications — don't ship development credentials
  • Reuse an access token until it expires rather than requesting a new one per call, and refresh once it expires
  • Monitor authentication failures through your issuer and Glean

Next Steps​

Use OAuth with an SDK

Pass an OAuth token to the TypeScript, Python, Go, or Java client

Client API Reference

Explore Client API endpoints that work with OAuth

Glean OAuth Authorization Server

Admin guide to enabling and configuring the Glean Authorization Server

Remote MCP Server

OAuth-authenticated MCP access powered by the Glean Authorization Server

Need Help?​

  • Admin Setup: Contact your Glean administrator for OAuth configuration
  • Provider Issues: Consult your identity provider documentation
  • API Issues: Check the Client API Reference
  • Community: Join discussions at community.glean.com