Building with PATs

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

.NET SDK - See .NET SDK Authentication

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

Go to your Speckle Server (for example, app.speckle.systems) and sign in.

Open Developer settings

Open the workspace switcher (the workspace name at the top of the left sidebar), select your name, then open Developer. Your name is the link to User settings, not only a signed-in label. See Open user settings.

Create a token

Select 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/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.

Overview

Getting Started

Building Custom Apps

Building Integrations

Using PATs

Getting a Personal Access Token

Using the Token