Token Scopes

API tokens in Bklit can be scoped to specific projects and domains for security and organization.

Project Scoping

What is Project Scoping?

When you create a token, you must select which projects it can access. The token will only be able to send analytics data to those specific projects.

Why Use Project Scoping?

• Security - Limit access to only necessary projects
• Organization - Separate tokens for different projects
• Control - Manage access at a granular level

Example Use Cases

Single Project Token

• Token scoped to "Production Website"
• Can only send data to that project
• Use for production applications

Multi-Project Token

• Token scoped to "Staging" and "Development"
• Can send data to both projects
• Use for testing across environments

Domain Restrictions

What are Domain Restrictions?

Domain restrictions limit which domains can use a token. This prevents unauthorized use of your tokens.

How It Works

When a request is made with a token:

1. Bklit checks the request origin
2. Verifies it matches an allowed domain
3. Rejects requests from unauthorized domains

Setting Domain Restrictions

When creating a token, you can add allowed domains:

example.com
www.example.com
app.example.com

Domain Matching

• Exact match required
• Subdomains must be explicitly added
• example.com does NOT match www.example.com

Examples

Allowed:

• Token allows example.com
• Request from https://example.com ✅
• Request from http://example.com ✅

Not Allowed:

• Token allows example.com
• Request from https://www.example.com ❌
• Request from https://app.example.com ❌

Solution: Add all needed domains:

• example.com
• www.example.com
• app.example.com

Token Validation

Validation Process

When a request is made:

1. Token Authentication

   • Token is validated against stored hash
   • Token expiration is checked

2. Project Validation

   • Requested project ID is checked
   • Token must have access to the project

3. Domain Validation (if restrictions set)

   • Request origin is checked
   • Must match an allowed domain

Validation Errors

Invalid Token

Error: Invalid API token

• Token doesn't exist
• Token was deleted
• Token is expired

Project Access Denied

Error: Token does not have access to this project

• Token not scoped to requested project
• Project ID is incorrect

Domain Not Allowed

Error: Domain not allowed for this token

• Request origin doesn't match allowed domains
• Domain restrictions are too strict

Best Practices

Project Scoping

1. One token per project - For production, use separate tokens
2. Multi-project tokens - Only for development/testing
3. Regular review - Audit token access regularly

Domain Restrictions

1. Always set restrictions - Don't leave tokens unrestricted
2. Include all domains - Add production, staging, and development
3. Use subdomains - Add www and other subdomains explicitly
4. Test restrictions - Verify tokens work from allowed domains

Token Organization

Production Tokens

• Scoped to single production project
• Restricted to production domains
• Long expiration or no expiration

Development Tokens

• Scoped to development projects
• Restricted to localhost or staging domains
• Short expiration dates

Testing Tokens

• Scoped to test projects
• No domain restrictions (for flexibility)
• Very short expiration

Examples

Production Token

Name: Production Website Token
Projects: [Production Website]
Domains: [example.com, www.example.com]
Expiration: None

Development Token

Name: Local Development Token
Projects: [Development, Staging]
Domains: [localhost, 127.0.0.1]
Expiration: 30 days

Multi-Environment Token

Name: All Environments Token
Projects: [Production, Staging, Development]
Domains: [example.com, staging.example.com, localhost]
Expiration: 90 days

Troubleshooting

Token Works Locally But Not in Production

• Check domain restrictions include production domain
• Verify token is scoped to production project
• Check token hasn't expired

Token Rejected from Subdomain

• Add subdomain explicitly to allowed domains
• Verify exact domain name matches
• Check for typos in domain list

Token Works But Wrong Project

• Verify project ID in request matches token scope
• Check token has access to requested project
• Review token project assignments

Related Documentation

• Creating Tokens - How to create tokens
• Token Security - Security best practices
• SDK Integration - Using tokens with the SDK