# Achiral auth.md

This document describes the public authentication and agent registration posture for Achiral AI developer and agent integrations.

## Audience

This file is for AI agents, developers, scanners, and integration tooling that need to understand how to register for or use Achiral API and MCP credentials.

## Current Authentication Model

Achiral currently supports account-based workspace access and scoped bearer credentials. Achiral does not currently publish a public OAuth 2.0 authorization server or OpenID Connect issuer for third-party agent account linking.

Supported credential use:

```http
Authorization: Bearer acm_...
```

Supported credential families:

- Achiral workspace sessions for browser access at https://app.achiral.ai.
- Scoped Achiral Context Access Tokens for API access.
- Scoped Achiral MCP tokens for authenticated MCP tool execution.

Public MCP discovery is unauthenticated. MCP tool execution requires an authenticated bearer token.

## Registration and Provisioning

Human operators create or join an Achiral workspace from:

- https://app.achiral.ai/start
- https://app.achiral.ai/login

Workspace owners and admins provision scoped credentials inside the authenticated Achiral application. Agents should not probe registration endpoints during passive scans because registration can create accounts, send email, or issue credentials.

## Agent Credential Methods

### Scoped Bearer Token

Use this method for Achiral Memory API and authenticated MCP execution when a workspace owner or admin has provisioned an Achiral token.

- Credential type: bearer token
- Token prefix: `acm_`
- Header: `Authorization: Bearer <token>`
- Scope model: explicit, least-privilege scopes
- Provisioning: authenticated Achiral workspace UI or approved administrative workflow

Common scopes include:

- `knowledge:read`
- `insights:read`
- `memory:read`
- `memory:write`
- `memory:control`
- `memory:delete`
- `actions:request`
- `inference:chat`

## Public Discovery Resources

- OpenAPI specification: https://achiral.ai/openapi.json
- API catalog: https://achiral.ai/.well-known/api-catalog
- LLM index: https://achiral.ai/llms.txt
- Developer Memory API docs: https://achiral.ai/docs/memory/api/developer-memory-api
- Achiral CLI: https://www.npmjs.com/package/@achiral/cli
- MCP discovery endpoint: https://mcp.achiral.ai/mcp
- MCP manifest: https://mcp.achiral.ai/.well-known/achiral-mcp.json
- MCP public tool schemas: https://mcp.achiral.ai/.well-known/achiral-mcp-tools.json
- MCP protected resource metadata: https://mcp.achiral.ai/.well-known/oauth-protected-resource

## OAuth and OpenID Connect

Achiral does not currently advertise `/.well-known/oauth-authorization-server` or `/.well-known/openid-configuration` because those endpoints require a live authorization server behind them.

When Achiral intentionally ships public OAuth or OpenID Connect account linking for agents, this document will link to the authorization server metadata and include the corresponding agent registration method.