For how to create a personal access token or register an OAuth application, see Building with PATs and OAuth 2.0. This page covers the .NET-specific code that consumes them.
Account:
- Personal access token — scripts, services, and CI (recommended default)
- Interactive browser login — desktop and connector apps that should integrate with Speckle’s existing account store
- Locally stored accounts — reuse a login from Speckle desktop connectors
Choosing an Authentication Method
- A script, service, automation, or CI/CD pipeline — use a personal access token via
IAccountFactory.CreateAccount. Doesn’t touchAccounts.db— in-memory only. - A multi-user server or web backend that already manages its own user tokens — perform your own OAuth exchange (see OAuth 2.0), then pass the resulting token to
IAccountFactory.CreateAccount. Doesn’t touchAccounts.db— in-memory only. - A desktop connector or CLI tool meant to share login state with Speckle’s desktop ecosystem — use interactive login via
IAccountManager.AuthenticateAccount. Always writes toAccounts.db, by design. - Any app reusing a login a user already created via a Speckle desktop connector or
AuthenticateAccount— use locally stored accounts viaGetAccounts/GetDefaultAccount. Read-only access toAccounts.db.
Token-based authentication (recommended for AEC scripts)
The recommended approach for most AEC automation scripts: build anAccount from a personal access token using IAccountFactory.
IAccountFactory.CreateAccount fetches user and server info from the token and returns an Account object. It does not write to the local account store — it’s a lightweight factory for in-memory use, ideal for scripts, services, and CI.Use Environment Variables (Recommended)
- Linux/macOS
- Windows (PowerShell)
- CI/CD
Interactive login (connectors and desktop apps)
Avoid this section unless you are building a connector or desktop tool. For scripts, QA automations, and Grasshopper send/receive, use a PAT from the section above. For desktop or connector-style applications where a user should sign in through the browser and you want that login to be reusable across Speckle’s desktop ecosystem, useIAccountManager.AuthenticateAccount. This opens a browser window and completes an OAuth PKCE flow.
Reusing Locally Stored Accounts
If a user has already signed in via a Speckle desktop connector, or viaAuthenticateAccount above, retrieve their stored accounts instead of prompting again:
Different Speckle Servers
Checking Authentication Status
Common Authentication Errors
SpeckleException: GraphQL response indicated that the ActiveUser could not be found
SpeckleException: GraphQL response indicated that the ActiveUser could not be found
Cause: The token is invalid, expired, or has been revoked.Solution: Generate a new personal access token and verify there are no extra spaces when copying it.
No accounts returned by GetAccounts / GetDefaultAccount
No accounts returned by GetAccounts / GetDefaultAccount
Cause: No account has been authenticated on this machine yet.Solution: Use token-based authentication via
IAccountFactory.CreateAccount, or call AuthenticateAccount to sign in interactively first.HTTP connection errors to a self-hosted server
HTTP connection errors to a self-hosted server
Cause: The server URL is incorrect, or the server uses a self-signed certificate.Solution: Verify the server URL, check network/firewall settings, and ensure the certificate is trusted by the host machine — Speckle.Sdk does not expose a certificate-bypass option.
Security Best Practices
Do:
- Store tokens in environment variables or a secret manager
- Use scoped tokens with the minimum permissions your application needs
- Revoke tokens when they’re no longer needed
Next Steps
Build your first model analysis tool
Load model data after authenticating
Automate with scripts
Bootstrap and Receive2
Core concepts
Platform map and mental model