Skip to main content

Authentication

SemanticFed clients authenticate through the Burdenoff identity layer. All workspace operations require dual-token auth: a platform token plus a workspace token. The workspace token is issued automatically when you select a workspace.

Supported flows​

FlowBest forClient
OAuth2 Device CodeTerminal/CLI, browser extensions, MCPCLI, Browser Ext, VS Code
OAuth2 Authorization Code + PKCEWeb apps, mobile appsApp Shell
Client CredentialsMachine-to-machine, automationSDKs, scripts
Email / PasswordLegacy integrations, testingSDKs

OAuth2 Device Code​

Interactive browser-based login for terminal clients.

CLI​

semanticfed auth login

The CLI prints a user code and verification URL. Open the URL in a browser, enter the code, and approve. Tokens are stored at ~/.config/semanticfed-cli/auth.json (mode 0600).

Node SDK​

const { userCode, verificationUri, promise } = await sdk.auth.loginWithDeviceCode();
console.log(`Open ${verificationUri} and enter: ${userCode}`);
const tokens = await promise;

Python SDK​

# Device code is handled via the auth module
await sdk.auth.sign_in(email="[email protected]", password="secret")

OAuth2 Authorization Code + PKCE​

For web apps and redirects.

const challenge = sdk.auth.getAuthorizationUrl({
  redirectUri: 'http://localhost:8400/callback',
  scopes: ['openid', 'profile', 'email', 'offline_access'],
});
// Redirect user to challenge.url, then exchange:
const tokens = await sdk.auth.exchangeAuthCode(code, challenge.codeVerifier, challenge.redirectUri);

Client Credentials (M2M)​

For service accounts and automation.

const result = await sdk.auth.authenticateApp(clientId, clientSecret);

Token management​

CLI​

semanticfed auth status                # Current auth state
semanticfed auth token                 # Platform access token
semanticfed auth token --workspace     # Workspace token
semanticfed auth refresh               # Force refresh
semanticfed auth logout                # Clear all tokens

SDKs​

Both Node and Python SDKs support automatic token refresh. You can also hook into refreshes:

const sdk = new SemanticFedSDK({
  autoRefresh: true,
  onTokenRefresh: (tokens) => {
    console.log('Tokens refreshed');
  },
});

Workspace token​

After authentication, issue a workspace-scoped token:

await sdk.auth.issueWorkspaceToken(workspaceId, organizationId);

In the CLI, this happens automatically when you run:

semanticfed workspace set <id>

Environment and endpoints​

Authentication endpoints follow the same BURDENOFF_ENV rules as the rest of the ecosystem:

BURDENOFF_ENVOIDC issuerDefault client ID
prod (default)https://graphql.burdenoff.com/globalburdenoff_cli_semanticfed
alphahttps://alphagraphql.burdenoff.com/globalburdenoff_cli_semanticfed
localhttp://localhost:4000/globalburdenoff_cli_semanticfed

Security notes​

  • Tokens are stored with mode 0600 where the filesystem supports it.
  • Workspace tokens are scoped to a single workspace and auto-refresh.
  • Platform tokens refresh every ~1 hour; workspace tokens every ~15 minutes.
  • Never commit tokens or auth files to version control.

Next steps​