Skip to main content

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
warning

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:

Authorization: Bearer <user_scoped_token>

Header Details

HeaderRequired ForDescriptionExample Value
AuthorizationAll tokensBearer token authenticationBearer glean_XYZ123...
X-Glean-ActAsGlobal tokens onlyEmail of user to impersonateuser@company.com

Token Types

Choose the right token type for your use case:

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

Creating Tokens

Follow these steps to create Glean-issued tokens:

1

Navigate to Token Management

Go to Client API Token Settings (admin access required)

2

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
3

Save Token Securely

warning

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
ScopeDescriptionExample Endpoints
ACTIVITYUser activity collectionActivity reporting APIs
AGENTSGlean AgentsAgent creation, execution
ANNOUNCEMENTSCompany announcementsCreate, update announcements
ANSWERSGlean AnswersManage Q&A content
CHATGleanChat functionalityChat API, conversations
COLLECTIONSContent collectionsCreate, manage collections
DOCPERMISSIONSDocument permissionsAccess control management
DOCUMENTSDocument operationsDocument retrieval, metadata
ENTITIESEntity dataPeople, organizational data
FEEDBACKUser feedbackFeedback collection
INSIGHTSAnalytics insightsUsage analytics, reports
PEOPLEPeople directoryEmployee information
PINSPinned contentContent pinning features
SEARCHSearch functionalitySearch queries, autocomplete
SHORTCUTSGoLinks/shortcutsShortcut management
SUMMARIZEAI summarizationDocument summarization
VERIFICATIONContent verificationDocument verification
warning

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

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

Expected Response

Successful authentication returns a 200 status with search results:

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

Troubleshooting Glean Tokens

Common Token Errors

ErrorCauseSolution
401 UnauthorizedInvalid or expired tokenVerify token is correct and not expired
403 ForbiddenInsufficient scopesAdd required scopes to token
400 Bad Request: Required header missing: X-Glean-ActAsMissing header for global tokenAdd X-Glean-ActAs header
401 Invalid identityInvalid email in X-Glean-ActAsVerify email is valid and user exists

Debugging Steps

1

Verify token validity

Check that your token hasn't expired and is correctly formatted

2

Confirm headers

Ensure you have the correct headers for your token type:

  • User token: Authorization only
  • Global token: Authorization + X-Glean-ActAs
3

Check token scopes

Verify your token has the required scopes for the endpoint you're accessing

4

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 CaseRecommended ScopesNotes
Search ApplicationSEARCH, DOCUMENTSBasic search functionality
Chat IntegrationCHAT, SEARCHChat with search capabilities
Analytics DashboardINSIGHTS, ACTIVITYUsage analytics and reporting
Content ManagementCOLLECTIONS, PINS, SHORTCUTSContent organization features
Admin ToolMultiple scopes as neededConsider 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


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