---
title: Authentication & environments
description: Understand Basalt personal access tokens, Handoff clients, service principals, sessions, mappings, and origin boundaries.
slug: authentication
path: /authentication
section: Fundamentals
availability: supported
nav_order: 3
canonical_url: https://developers.basaltnotes.com/authentication
markdown_url: https://developers.basaltnotes.com/authentication.md
mirror_url: https://basaltnotes.com/developers/authentication
---
# Authentication & environments

Basalt separates **who is calling**, **what product is calling**, and **which workspace/vault the caller may access**. Do not collapse those identities into one token or route parameter.

## Personal access tokens

Hosted MCP and the Developer REST API use separate, server-authoritative plan entitlements. Premium and Professional include bounded MCP access without Developer REST API access; Developer & Agent and Team include both capabilities.

1. In Basalt, open **Settings → AI Connections & API**.
2. Create a personal access token.
3. Store it as a secret; do not place it in client-side JavaScript, public repositories, redirect URLs, or analytics.
4. Send it as:

```http
Authorization: Bearer bda_…
```

PATs are account-bound and plan-bound. Rotate a token if it may have been exposed.

## Handoff client credentials

Handoff creation uses a separate scoped client identity:

```http
Authorization: Bearer bhc_…
```

Keep Handoff client credentials in your backend. The `continueUrl` returned by Basalt contains an opaque one-time token and must not contain the client credential or Handoff payload.

## Product Runtime service principals

A product installation should not use an employee's personal token as its long-lived identity. Approved product integrations use an installation service principal scoped through:

```text
organization
→ product definition
→ customer installation
→ service principal
→ credential scopes
→ organization workspace assignment
→ installation logical-vault grant
```

Revoking any required link must remove future access without deleting the user's knowledge.

## First-party browser sessions

First-party Basalt product surfaces may use authenticated Basalt sessions where the runtime explicitly supports them. Independent origins should use an explicit bearer credential. Do not copy Basalt cookies into another product.

## Identifiers are not authority

These values identify targets but do not grant access:

- `mappingId`
- `workspaceId`
- logical `vaultId`
- `scopeId`
- Product Experience ID
- product hostname
- organization ID

The server must resolve current account, workspace, organization, installation, and vault authority for the authenticated principal.

## Mapping IDs

Developer REST and most MCP vault tools require an explicit Basalt Hosted `mappingId`. You may provide it where supported in the request body/query or through:

```http
X-Basalt-Mapping: <mapping-uuid>
```

A mapping is an explicit hosted-vault target, not a default “current vault.”

## Origins and CORS

Browser-origin trust and data authorization are separate checks. A verified first-party/custom Product Experience origin can be trusted for the browser request boundary without gaining data access. Workspace membership, product installation grants, and logical-vault grants remain authoritative.

## Environment guidance

Use different credentials for development and production. Never reuse production bearer credentials in local examples, recorded demos, CI logs, or documentation screenshots.

Handoff references require HTTPS except where the contract explicitly permits localhost HTTP for development.