Getting a Personal Access Token
1
Log into Speckle
Go to your Speckle Server (e.g., app.speckle.systems)
2
Access Your Profile
Click your avatar → Settings → Profile → Developer → Access Tokens
3
Create Token
Click “New Token”, give it a name, select the required scopes, then copy the token.
Authentication Methods
Personal Access Tokens (PATs)
Best for: Single-user tools, server-side applications, scripts, and automation Personal Access Tokens allow users to authenticate and interact with the Speckle API on their own behalf. They’re ideal for:- Command-line tools
- Server-side applications
- Automation scripts
- Single-user integrations
Using PATs
PATs can be used with any Speckle SDK or API:- Python SDK - See Python SDK Authentication Guide for detailed examples
- GraphQL API - Include token in
Authorization: Bearer YOUR_TOKENheader - JavaScript/TypeScript - Use tokens in API client configuration
OAuth2 Authorization Code Flow with PKCE
Best for: Multi-user web applications, public-facing apps, third-party integrations OAuth2 with Proof Key for Code Exchange (PKCE) is the recommended method for web applications that need to authenticate multiple users. PKCE enhances security by ensuring authorization codes cannot be intercepted or reused.How OAuth2 with PKCE Works
- Generate Code Verifier & Challenge: Your app generates a random code verifier and its SHA256 hash (code challenge)
- Redirect to Authorization: User is redirected to Speckle’s authorization endpoint
- User Authorizes: User logs in and grants permissions to your app
- Receive Authorization Code: Speckle redirects back with an authorization code
- Exchange for Token: Your app exchanges the code + verifier for an access token
Registering Your Application
Before using OAuth2, you need to register your application:1
Access Developer Settings
Go to your Speckle Server → Avatar → Settings → Profile → Developer → Apps
2
Create New App
Click “New App” and provide:
- App Name: Display name for your application
- Redirect URIs: Valid redirect URIs (e.g.,
https://yourapp.com/callback) - Scopes: Permissions your app needs
3
Save Credentials
Copy your App ID and App Secret (keep secret secure!)
Redirect URIs: Must match exactly. For development, you can use
http://localhost:3000/callback. For production, use your actual domain.Implementing OAuth2 with PKCE
Using the speckle-auth package (Recommended): The community-maintained speckle-auth package simplifies OAuth2 implementation by handling PKCE generation, state management, and token exchange automatically. Manual Implementation: If implementing OAuth2 manually, you’ll need to:- Generate PKCE code verifier and challenge (SHA256 hash)
- Redirect users to Speckle’s authorization endpoint with the challenge
- Handle the callback and exchange the authorization code for an access token
- Store the token securely for subsequent API calls
For complete OAuth2 implementation examples, see the Building Custom Apps guide or the speckle-auth package documentation.
App Registration and Management
Managing App Permissions
Once registered, your application can request specific scopes that define the level of access to user data. Users can review and revoke these permissions at any time through their account settings. Common Scopes:| Scope | Description | Use Case |
|---|---|---|
streams:read | Read project data | View-only applications |
streams:write | Create and modify projects | Data management apps |
profile:read | Read user profile | Display user information |
profile:email | Access user email | User identification |
Users can review and revoke app permissions at any time: Avatar → Settings → Profile → Developer → Authorized Apps
Updating App Settings
You can update your app’s settings at any time:- Redirect URIs: Add or modify allowed redirect URIs
- Scopes: Update requested permissions (requires re-authorization)
- App Name: Change the display name
- Revoke Access: Users can revoke access to your app
Choosing the Right Method
Use Personal Access Tokens
When:
- Single-user tools or scripts
- Server-side applications
- Automation and CI/CD
- Personal development projects
Use OAuth2 with PKCE
When:
- Multi-user web applications
- Public-facing apps
- Third-party integrations
- Apps requiring user consent
Security Best Practices
Scope Limitation
When creating tokens or registering applications, request only the minimum necessary scopes. This principle of least privilege reduces potential security risks.Do:
- Request only scopes you actually need
- Review and audit requested scopes regularly
- Document why each scope is required
- Use read-only scopes when possible
Token Management
Treat all tokens as sensitive information. Proper token management is critical for security.Do:
- Store tokens in environment variables
- Use
.gitignoreto exclude.envfiles - Rotate tokens periodically
- Use scoped tokens with minimal permissions
- Revoke tokens when no longer needed
- Use secure storage (keychain, secret managers) in production
- Implement token refresh for OAuth2 tokens
Token Compromise Response
If a token is compromised:- Revoke immediately - Go to Settings → Developer → Access Tokens and revoke the compromised token
- Generate new token - Create a replacement with the same scopes
- Update application - Replace the token in your application
- Review access logs - Check for unauthorized access
- Rotate related credentials - If app secret was exposed, regenerate it
Community Resources
speckle-auth Package
For JavaScript/TypeScript developers, the community-maintained speckle-auth package simplifies the authentication process by providing utility functions for handling OAuth2 flows with Speckle. The package handles PKCE generation, state management, and token exchange automatically, making OAuth2 implementation much simpler. See the package documentation for installation and usage instructions.Next Steps
- Python SDK Authentication - Detailed Python authentication guide
- GraphQL API - Learn how to use tokens with GraphQL
- Getting Started - Continue with your first integration