# SaaS Custom Domains auth.md

How AI agents get access to the SaaS Custom Domains API.

## Audience

Agents working for a SaaS Custom Domains customer: creating upstreams and custom domains, checking DNS and certificate status, managing rules and redirects, and reading analytics through the API at `https://app.saascustomdomains.com/api/v1`.

## Registration

There is no self-service registration for agents. Agents that connect through the MCP server can sign in with OAuth (see below). For the REST API, a person with a SaaS Custom Domains account creates an API token and gives it to the agent:

1. Sign in at https://app.saascustomdomains.com, or sign up at https://app.saascustomdomains.com/users/sign_up (7-day free trial; a credit or debit card is required).
2. Open **Settings → API** (https://app.saascustomdomains.com/api_tokens) and create a token. Name it after the agent so it's easy to find and revoke later.
3. Give the token to the agent as a secret, for example the environment variable `SCD_API_TOKEN`. Don't paste it into prompts, logs or source control.

Supported methods:

| Method | Supported |
| --- | --- |
| API token created by a user in the dashboard | Yes |
| OAuth 2.1 sign-in (Client ID Metadata Documents or dynamic client registration, PKCE) | Yes, for the MCP server only |
| Browser sign-in from the CLI (`scd auth login`), which creates an API token | Yes |
| OAuth for the REST API | No |
| Identity assertions (ID-JAG), verified email, anonymous registration | No |

If the agent has no token, ask the user to create one with the steps above. Don't ask for their password.

## Using the credential

- Send `Authorization: Bearer <token>` on every request to `https://app.saascustomdomains.com/api/v1`.
- Check the token with `GET /api/v1/me`. A `401` with an empty body means the token is missing, wrong or deleted.
- A token acts as the user who created it and can use every account that user belongs to. It has no scopes, so treat it like a password.
- Find the account with `GET /api/v1/accounts`; most endpoints are under `/api/v1/accounts/{account_uuid}/`.
- The API allows 360 requests per minute per token. Over the limit you get `429` with `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
- Creating upstreams, custom domains and redirects needs an active subscription; without one the API returns `402`.

## MCP server

Agents that support MCP can use the remote MCP server at `https://mcp.saascustomdomains.com/mcp` instead of calling the API directly. It accepts two kinds of credential:

- **OAuth sign-in.** The protected resource metadata is at `https://mcp.saascustomdomains.com/.well-known/oauth-protected-resource/mcp` and the authorization server metadata at `https://mcp.saascustomdomains.com/.well-known/oauth-authorization-server`. The person approves the client, signs in to SaaS Custom Domains, and the client gets an access token. Behind it, an API token named after the client (for example "MCP: Claude") appears under **Settings → API**; deleting it disconnects the client.
- **An API token** in the `Authorization: Bearer <token>` header, as for the REST API.

The same rate limits apply either way. Setup for each client: https://docs.saascustomdomains.com/mcp.

## CLI

The [CLI](https://docs.saascustomdomains.com/cli) (`npx @saas-custom-domains/cli`) reads the token from `SCD_API_TOKEN`, which is the simplest choice for agents and CI. A person can also run `scd auth login` on their own computer: the browser opens, they sign in, and the CLI saves an API token named after the computer (for example "CLI: macbook"), listed under **Settings → API**.

## Revocation

The user deletes the token under **Settings → API**. It stops working right away. Tokens are independent, so revoking one agent's token doesn't affect others.

## Testing without a token

[scd-mock](https://github.com/saas-custom-domains/scd-mock) runs the API and proxy locally and accepts the token `scd_test_token`. No account is needed.

## More

- API reference for agents: https://docs.saascustomdomains.com/llms-full.txt
- OpenAPI spec: https://docs.saascustomdomains.com/openapi.json
- MCP server setup: https://docs.saascustomdomains.com/mcp
- CLI: https://docs.saascustomdomains.com/cli
- Skill for adding custom domains to an app: https://docs.saascustomdomains.com/.well-known/agent-skills/saas-custom-domains/SKILL.md