Authentication and Configuration

Configure Atlas environments and authenticate users across MCP, SDK, and API.

Atlas evaluates resource access under a user identity. Each surface establishes that identity during setup or per request.

​

Auth Responsibilities

Surface	Configuration	User auth	Developer auth
Local MCP	Local Atlas profile on the machine.	Signed-in local user token.	Not supplied by the MCP host. Atlas uses local MCP client configuration.
Remote MCP	Host connects to Atlas-hosted MCP.	Bearer token for the connected Atlas user.	Not supplied by the MCP host. Atlas uses remote MCP server configuration.
SDK	Client configured in application code.	Passed per request for user-owned resources.	Developer key in trusted application code.
API	HTTP endpoint and headers.	Bearer token on each request.	Developer key header for application integrations.

​

Auth Strategy

Atlas has one resource authorization rule across all surfaces: reads, writes, downloads, full object retrieval, run lifecycle operations, and action approvals execute under an Atlas user identity.

Local MCP uses a locally stored Atlas user token. Remote MCP validates a bearer token issued for Atlas. SDK and direct API integrations add developer identity so Atlas can attribute and govern the application in addition to the end user.

Remote MCP validates the connected user’s token at the MCP boundary and calls Atlas APIs under that user context. Downstream Atlas API calls require Atlas-issued user context.

​

Local MCP

Local MCP uses a signed-in Atlas profile on the machine.

atlas setup-url https://atlas.example.com
atlas login
atlas mcp serve

The local MCP server reads the local Atlas profile and sends remote Atlas calls under that user’s permissions.

​

Remote MCP

Remote MCP uses user-level bearer auth on the MCP HTTP connection.

POST /mcp HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
Content-Type: application/json

If the host connects without a token, Atlas returns an OAuth challenge. The host completes Atlas auth for the connected user and reconnects with the user token.

The token must be an Atlas user token scoped for the Atlas MCP server. Atlas validates it on every remote MCP request.

​

SDK

The Atlas SDK defaults to M2M client credentials. A Bearer token is also supported. Do not set both.

import { Atlas } from '@arena-physica/atlas'

const atlas = new Atlas({
  baseUrl: 'https://your-atlas-domain',
  clientId: process.env.ATLAS_CLIENT_ID,
  clientSecret: process.env.ATLAS_CLIENT_SECRET,
})

M2M credentials identify a trusted application and inherit the groups granted to that client. A user token identifies the signed-in Atlas user.

Client secrets belong on trusted servers, jobs, notebooks, or internal tools. Do not put clientSecret in a browser bundle.

​

API

API calls include the Atlas user token. Application integrations also include developer identity.

POST /api/v1/agentic/requests HTTP/1.1
Host: atlas.example.com
Authorization: Bearer <atlas-user-access-token>
X-Atlas-Developer-Key: <developer-key>
Content-Type: application/json