Glean-Issued Tokens for Client API
Glean-issued tokens provide an alternative to OAuth when you need granular scope control or don't have OAuth infrastructure. They're manually created through the admin console and offer fine-grained permissions.
Glean Token Benefits
- Granular scope control - Limit access to specific API endpoints
- User-scoped or global - Choose appropriate permission level
- No external dependencies - Works without identity provider setup
- Flexible expiration - Set custom expiry dates
Glean tokens work with both Client API and Indexing API, but this guide focuses on Client API usage. For Indexing API, see the Indexing API Authentication guide.
Authentication Headers
Glean token requests use different headers based on token type:
- User-Scoped Token
- Global Token
Authorization: Bearer <user_scoped_token>
Authorization: Bearer <global_token>
X-Glean-ActAs: user@company.com
Header Details
Header | Required For | Description | Example Value |
---|---|---|---|
Authorization | All tokens | Bearer token authentication | Bearer glean_XYZ123... |
X-Glean-ActAs | Global tokens only | Email of user to impersonate | user@company.com |
Token Types
Choose the right token type for your use case:
- User-Scoped (Recommended)
- Global (Super Admin Only)
Best for: Most applications, user-specific integrations
- Security: Highest security, limited to specific user's data
- Headers: Only
Authorization: Bearer <token>
required - Creation: Admins can create for any user, API Token Creators for themselves
- Use case: Applications accessing data as a specific user
curl -X POST https://instance-be.glean.com/rest/api/v1/search \
-H 'Authorization: Bearer <USER_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{"query": "quarterly reports"}'
Best for: Multi-user applications, service integrations
- Security: Can impersonate any user (use carefully)
- Headers: Requires
X-Glean-ActAs
header with user email - Creation: Only Super Admins can create these tokens
- Use case: Applications serving multiple users
curl -X POST https://instance-be.glean.com/rest/api/v1/search \
-H 'Authorization: Bearer <GLOBAL_TOKEN>' \
-H 'X-Glean-ActAs: user@company.com' \
-H 'Content-Type: application/json' \
-d '{"query": "quarterly reports"}'
The X-Glean-ActAs
header is required for global tokens. Requests without this header will fail.
Creating Tokens
Follow these steps to create Glean-issued tokens:
Navigate to Token Management
Go to Client API Token Settings (admin access required)
Add New Token
Click Add New Token and configure:
- Description: Helpful name for tracking
- Permissions: USER (recommended) or GLOBAL
- Scopes: Select required API access scopes
- Expires: Optional expiration date
- User Email: Required for USER tokens
Save Token Securely
The token secret is only shown once after creation. Save it securely - you cannot retrieve it again.
Available Scopes
Scopes control which Client API endpoints your token can access:
Complete Scopes Reference
Scope | Description | Example Endpoints |
---|---|---|
ACTIVITY | User activity collection | Activity reporting APIs |
AGENTS | Glean Agents | Agent creation, execution |
ANNOUNCEMENTS | Company announcements | Create, update announcements |
ANSWERS | Glean Answers | Manage Q&A content |
CHAT | GleanChat functionality | Chat API, conversations |
COLLECTIONS | Content collections | Create, manage collections |
DOCPERMISSIONS | Document permissions | Access control management |
DOCUMENTS | Document operations | Document retrieval, metadata |
ENTITIES | Entity data | People, organizational data |
FEEDBACK | User feedback | Feedback collection |
INSIGHTS | Analytics insights | Usage analytics, reports |
PEOPLE | People directory | Employee information |
PINS | Pinned content | Content pinning features |
SEARCH | Search functionality | Search queries, autocomplete |
SHORTCUTS | GoLinks/shortcuts | Shortcut management |
SUMMARIZE | AI summarization | Document summarization |
VERIFICATION | Content verification | Document verification |
Token permissions and scopes cannot be changed after creation. Plan carefully when creating tokens.
Implementation Examples
Search with 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": "quarterly reports",
"pageSize": 10
}'
Search with Global Token
curl -X POST https://instance-be.glean.com/rest/api/v1/search \
-H 'Authorization: Bearer <GLOBAL_TOKEN>' \
-H 'X-Glean-ActAs: user@company.com' \
-H 'Content-Type: application/json' \
-d '{
"query": "quarterly reports",
"pageSize": 10
}'
Chat with Glean Token
curl -X POST https://instance-be.glean.com/rest/api/v1/chat \
-H 'Authorization: Bearer <USER_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"query": "What are the latest quarterly results?",
"conversationId": "optional-conversation-id"
}'
Testing Glean Tokens
Test Commands
- User-Scoped Token
- Global 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}'
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": "..."
}
Troubleshooting Glean Tokens
Common Token Errors
Error | Cause | Solution |
---|---|---|
401 Unauthorized | Invalid or expired token | Verify token is correct and not expired |
403 Forbidden | Insufficient scopes | Add required scopes to token |
400 Bad Request: Required header missing: X-Glean-ActAs | Missing header for global token | Add X-Glean-ActAs header |
401 Invalid identity | Invalid email in X-Glean-ActAs | Verify email is valid and user exists |
Debugging Steps
Verify token validity
Check that your token hasn't expired and is correctly formatted
Confirm headers
Ensure you have the correct headers for your token type:
- User token:
Authorization
only - Global token:
Authorization
+X-Glean-ActAs
Check token scopes
Verify your token has the required scopes for the endpoint you're accessing
Test with simple endpoint
Start with a basic search request before testing complex operations
Token Management Best Practices
Security
- Use USER tokens over GLOBAL tokens when possible
- Set expiration dates for tokens used in temporary integrations
- Store tokens securely - never commit tokens to version control
- Use environment variables for token storage in applications
- Rotate tokens regularly for long-lived integrations
Development
- Create separate tokens for development, staging, and production
- Use descriptive names for tokens to track their purpose
- Test with minimal scopes first, then expand as needed
- Plan token architecture early - scopes cannot be changed after creation
Monitoring
- Monitor token usage through Glean's admin console
- Implement proper error handling for authentication failures
- Log authentication events for debugging and auditing
- Set up alerts for token expiration
Scope Planning Guide
Choose the right scopes for your application:
Common Scope Combinations
Use Case | Recommended Scopes | Notes |
---|---|---|
Search Application | SEARCH , DOCUMENTS | Basic search functionality |
Chat Integration | CHAT , SEARCH | Chat with search capabilities |
Analytics Dashboard | INSIGHTS , ACTIVITY | Usage analytics and reporting |
Content Management | COLLECTIONS , PINS , SHORTCUTS | Content organization features |
Admin Tool | Multiple scopes as needed | Consider global token for multi-user access |
Scope Selection Tips
- Start minimal - Add only scopes you immediately need
- Review regularly - Audit which scopes are actually used
- Document decisions - Record why specific scopes were chosen
- Test thoroughly - Verify all required functionality works
Next Steps
Client API Reference
Explore available Client API endpoints and their scope requirements
Token Management
Manage your Glean tokens in the admin console
Migration from OAuth
If you're considering switching from OAuth to Glean tokens:
When to Use Glean Tokens Instead of OAuth
- Need granular scope control - OAuth provides full API access
- Don't have identity provider - Glean tokens work independently
- Require global permissions - Global tokens can impersonate users
- Need custom expiration - More control over token lifecycle
Migration Considerations
- Scope mapping - Determine which scopes match your OAuth usage
- Header changes - Update authentication headers in your code
- Permission model - Understand user vs global token implications
- Testing - Thoroughly test with new token type
Need Help?
- Token Creation: Contact your Glean administrator for token creation access
- Scope Questions: Review Client API Reference for endpoint requirements
- Technical Issues: Check troubleshooting section above
- Community: Join discussions at community.glean.com