Skip to main content

​
Using PATs

Best for: Single-user tools, server-side applications, scripts, and automations. 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
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_TOKEN header
  • JavaScript/TypeScript - Use tokens in API client configuration
Never use PATs in client-side code. They provide full access to the user’s account and should only be used in secure, server-side environments.
Store tokens securely! Treat them like passwords—never commit them to version control or share them publicly. Use environment variables or secret management systems in production.

​
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.
When creating tokens or registering applications, request only the minimum necessary scopes. This principle of least privilege reduces potential security risks.

​
Using the Token

When making API requests, include the token in the Authorization header: 
fetch('https://app.speckle.systems/api/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer YOUR_TOKEN`,
  },
  body: JSON.stringify({ query: YOUR_GRAPHQL_QUERY }),
})
  .then(response => response.json())
  .then(data => console.log(data));
This request will act on behalf of the user who owns the token, with permissions defined by the selected scopes. This means if you have a token with streams:read scope, you can read project data but cannot modify it.
Last modified on March 26, 2026