API Overview/Authentication

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)

Glean Authorization Server or your IdP

Tokens from the Glean OAuth Authorization Server (incl. DCR) or an external IdP
Works with Google, Azure, Okta, OneLogin
Glean-defined scopes (Authorization Server) or Client API access via your IdP
Powers the remote MCP server

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:

Have an existing identity provider (Google, Azure, Okta, OneLogin)
Want standards-based authentication without creating Glean tokens
Prefer leveraging existing enterprise authentication
Need production-ready authentication quickly

Choose Glean Tokens if you:

Need granular scope control for security
Don't have an OAuth identity provider
Need global permissions to impersonate users
Want fine-grained control over token lifecycle

Authentication Headers Reference

Different authentication methods require different headers:

OAuth
User-Scoped Token
Global Token

Authorization: Bearer <oauth_access_token>
X-Glean-Auth-Type: OAUTH   # required for external-IdP tokens; optional for Glean Authorization Server tokens

Authorization: Bearer <user_scoped_token>

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

Quick Start

Choose your authentication method

Use the decision guide above to pick OAuth or Glean tokens

Follow the detailed setup guide

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

Test your integration

Use the test commands in your chosen guide to verify authentication

Build your application

Start building with the Client API Reference

Testing Your Authentication

Quick Test Commands

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

OAuth
User-Scoped Token
Global Token

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}'

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}'

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

OAuth (Recommended)

Glean Tokens (Alternative)

Quick Decision Guide​

Choose OAuth if you:​

Choose Glean Tokens if you:​

Authentication Headers Reference​

Quick Start​

Testing Your Authentication​

Quick Test Commands​

Expected Response​

Common Authentication Errors​

Best Practices​

Security​

Development​

Implementation Guides​