# Dakota auth.md

Dakota's marketing site at <https://dakota.xyz> is public. This document
describes how authentication works for humans and for AI agents acting on
behalf of a Dakota customer.

## Status

`dakota.xyz` is a marketing origin and issues no tokens of its own. Programmatic
access runs against two other origins:

| Origin | Role |
| --- | --- |
| `https://api.platform.dakota.xyz` | Dakota Platform REST API |
| `https://mcp.platform.dakota.xyz` | MCP server, and the OAuth 2.0 authorization server for it |

This is why `dakota.xyz` does not serve
`/.well-known/oauth-authorization-server` or
`/.well-known/openid-configuration`. Publishing them here would claim that the
marketing origin issues tokens, which it does not. The real metadata is listed
under "Agent access" below, on the origin that actually issues the tokens.

## Agent audience

Agents acting on behalf of a Dakota customer, or running automated workflows
against a Dakota account, are the intended audience for this file. Public
marketing content does not require authentication and can be fetched by any
well-behaved crawler.

## Human authentication

Dakota uses [Stytch](https://stytch.com) for human sign-in to the marketing and
dashboard site (passwordless email links and session JWTs). The Dakota web app
reads the `stytch_session_jwt` cookie to authorize access to dashboard,
accounts, and operational routes. Stytch is the authorization server for those
sessions; `dakota.xyz` is not.

## Agent access

### OAuth 2.0

The Dakota MCP server is an OAuth 2.0 protected resource and publishes standard
metadata:

- Authorization server metadata (RFC 8414):
  <https://mcp.platform.dakota.xyz/.well-known/oauth-authorization-server>
- Protected resource metadata (RFC 9728):
  <https://mcp.platform.dakota.xyz/.well-known/oauth-protected-resource>

The authorization server supports the authorization code grant with PKCE
(`S256`), refresh tokens, and dynamic client registration at
`https://mcp.platform.dakota.xyz/oauth/register`. Scope `read` is supported
today. Sign-in is available with any Google account that has been invited to
your Dakota organization.

### API keys

An API key is the alternative to OAuth. Create one in the Dakota platform
dashboard under API keys. The key carries the same permissions as the user
account that created it, so store it in a password manager and never in plain
text or in a repository.

### Credential usage

Present credentials to the REST API as `Authorization: Bearer <token>`. The MCP
server accepts a bearer token or an `X-API-Key` header. Tokens are scoped to a
single Dakota customer and follow that customer's role and limit configuration.

Start against the sandbox at `https://api.platform.sandbox.dakota.xyz` before
using production credentials.

### Human contact for provisioning

- Email: <mailto:security@dakota.xyz>
- Sales: <https://dakota.xyz/talk-to-sales>
- Contact: <https://dakota.xyz/contact>
- Developer documentation: <https://docs.dakota.xyz>

## What this site exposes for agents today

| Surface | URL |
| --- | --- |
| Site map for AI agents | [`/llms.txt`](https://dakota.xyz/llms.txt) |
| API catalog (RFC 9727) | [`/.well-known/api-catalog`](https://dakota.xyz/.well-known/api-catalog) |
| MCP server manifest | [`/.well-known/mcp.json`](https://dakota.xyz/.well-known/mcp.json) |
| OpenAPI specification | [`docs.dakota.xyz/openapi.json`](https://docs.dakota.xyz/openapi.json) |
| Agent Skills discovery index | [`/.well-known/agent-skills/index.json`](https://dakota.xyz/.well-known/agent-skills/index.json) |
| `Link:` response headers (RFC 8288) | `/` |
| `Content-Signal:` directive | [`/robots.txt`](https://dakota.xyz/robots.txt) |
| Markdown content negotiation | `Accept: text/markdown` on `/` returns the markdown site map |
| JSON errors on unknown API paths | `/api/<anything>` returns a JSON 404 with a code and a hint |
| WebMCP tools | `navigator.modelContext.provideContext()` on marketing pages |

## Contact

Security and integration questions: <security@dakota.xyz>.
