Client API Authentication

This guide helps you choose and implement the right authentication method for Glean's Client API, which powers search, chat, collections, agents, and other user-facing functionality.

OAuth (Recommended for per-user integrations)

Glean Authorization Server or your IdP

• Tokens from the Glean OAuth Authorization Server or an external IdP
• Works with Google, Azure, Okta, OneLogin
• Glean-defined scopes (Authorization Server) or Client API access via your IdP
• DCR for approved MCP hosts; static clients for governed applications

Setup OAuth →

Glean Tokens (Alternative)

Granular control and flexibility

• Fine-grained scope control
• User-scoped or global permissions
• Manual token management
• Best for specific use cases or testing

Setup Glean Tokens →

---

Quick Decision Guide

Choose your authentication method based on your needs:

Choose OAuth if you:

• Are building a per-user Client API integration
• Want users to authorize access without distributing Glean-issued API tokens
• Can use the Glean OAuth Authorization Server (enabled by default) or already use supported OAuth tokens from your enterprise identity provider
• Want the token issuer to manage expiration and refresh

Choose Glean-issued tokens if you:

• Call the Indexing API, which does not accept OAuth
• Need a global token with X-Glean-ActAs to impersonate users
• Have no OAuth path: the Glean OAuth Authorization Server is disabled and no external-IdP OAuth path is configured

---

Authentication Headers Reference

Different authentication methods require different headers:

Glean OAuth Authorization Server

Authorization: Bearer <oauth_access_token>

External IdP OAuth

Authorization: Bearer <oauth_access_token>
X-Glean-Auth-Type: OAUTH

User-Scoped Token

Authorization: Bearer <user_scoped_token>

Global Token

Authorization: Bearer <global_token>
X-Glean-ActAs: user@company.com

---

Quick Start

1

Choose your authentication method

Use the decision guide above to pick OAuth or Glean tokens

2

Follow the detailed setup guide

• OAuth: Complete OAuth Setup Guide
• Glean Tokens: Complete Glean Tokens Guide

3

Test your integration

Use the test commands in your chosen guide to verify authentication

4

Build your application

Start building with the Client API Reference

---

Testing Your Authentication

Use the Search API Explorer to test a Client API request against your own tenant. API Explorer tests Client API authentication only. It is not production sample code. Implement the OAuth flow and token handling in your application before you deploy.

Quick Test Commands

Replace <instance> with your Glean instance name (how to find):

Glean OAuth Authorization Server

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

External IdP OAuth

curl -X POST https://<instance>-be.glean.com/rest/api/v1/search \
  -H 'Authorization: Bearer <OAUTH_TOKEN>' \
  -H 'X-Glean-Auth-Type: OAUTH' \
  -H 'Content-Type: application/json' \
  -d '{"query": "test", "pageSize": 1}'

User-Scoped Token

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

Global Token

curl -X POST https://<instance>-be.glean.com/rest/api/v1/search \
  -H 'Authorization: Bearer <GLOBAL_TOKEN>' \
  -H 'X-Glean-ActAs: your-email@company.com' \
  -H 'Content-Type: application/json' \
  -d '{"query": "test", "pageSize": 1}'

Expected Response

Successful authentication returns a 200 status with search results:

{
  "results": [...],
  "trackingToken": "...",
  "requestId": "..."
}

---

Common Authentication Errors

Error	Likely Cause	Solution
401 Unauthorized	Invalid or expired token	Verify token is correct and not expired
403 Forbidden	Insufficient permissions	Check token scopes or OAuth settings
Missing X-Glean-Auth-Type header / Invalid Secret	External-IdP OAuth token sent without the auth-type header	Add X-Glean-Auth-Type: OAUTH (external-IdP tokens only; not needed for Glean Authorization Server tokens)
Required header missing: X-Glean-ActAs	Global token header missing	Add X-Glean-ActAs: user@email.com

For detailed troubleshooting, see your specific authentication guide.

---

Best Practices

Security

• Store tokens securely - Never commit tokens to version control
• Use environment variables for token storage in applications
• Implement proper error handling for authentication failures
• Monitor token usage through appropriate admin consoles

Development

• Test authentication first - Verify auth works before building features
• Create separate tokens for development, staging, and production
• Use descriptive names for tokens to track their purpose
• Plan your architecture early - some settings cannot be changed later

---

Implementation Guides

Ready to implement? Choose your path:

OAuth Authentication

Complete OAuth setup guide

• Provider-specific setup (Google, Azure, Okta, OneLogin)
• Configuration in Glean admin console
• Implementation examples and testing
• OAuth-specific troubleshooting

Glean-Issued Tokens

Complete Glean tokens guide

• Token creation and management
• Scope selection and planning
• User-scoped vs global tokens
• Token-specific troubleshooting

Datasource OAuth Redirects

Control post-auth redirects

• Per-request redirect URL for headless integrations
• Tenant-level default redirect configuration
• Full flow walkthrough

---

Next Steps

Client API Reference

Explore available Client API endpoints

Search Implementation

Learn advanced search techniques

Chat Integration

Build chat applications with Glean

---

Need Help?

• Getting Started: Use the decision guide above to choose your path
• Technical Issues: Check the detailed guides linked above
• Admin Access: Contact your Glean administrator for token creation or OAuth setup
• Community: Join discussions at community.glean.com