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)
Leverages your existing identity provider
- No token management required
- Works with Google, Azure, Okta, OneLogin
- Full API access without scope restrictions
- Best for production applications
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
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 full Client API access without managing scopes
- 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
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
- 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 | OAuth header not set | Add X-Glean-Auth-Type: OAUTH for OAuth |
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
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