# auth.md

Verdictan supports operator-managed onboarding for the control-plane API through email-verified account registration. Registration and verification do not return a bearer credential.

Use these supported surfaces:
- Control-plane API: `https://api.verdictan.com/v1`
- Auth.md skill: `https://verdictan.com/auth.md`
- Registration endpoint: `https://api.verdictan.com/v1/auth/register`
- Verification endpoint: `https://api.verdictan.com/v1/auth/verify-email`
- Human sign-in: `https://console.verdictan.com/login`
- Managed root-family status: `https://api.verdictan.com/v1/platform-endpoint-families/root-status`
- Runtime request reference: `https://docs.verdictan.com/docs/reference/runtime-request-families/`
- API token guide: `https://docs.verdictan.com/docs/guides/developer/api-key-management/`
- Managed endpoint locality guide: `https://docs.verdictan.com/docs/regions/overview/`

Managed public endpoints are a different publication-family layer. Root hosts `verdictan.com`, `eu.verdictan.com`, and `us.verdictan.com` expose discovery and status only. Published traffic hostnames use `*.ai.global.verdictan.com`, `*.ai.eu.verdictan.com`, and `*.ai.us.verdictan.com`. An organization must create a specified gateway publication from an eligible connected gateway. The region must have `admitted` status.

Those managed hosts do not mint browser sessions or replace API registration. Registration, email verification, human sign-in, and specified API-token creation are different steps.

At this time, Verdictan does not publish these authentication contracts:
- OAuth, OpenID Connect, or RFC 9728 protected-resource
- ID-JAG, Anonymous registration, or A2A
- Public JWKS or HTTP Message Signatures
Use a human-owned work email and an operator-created scoped Verdictan API token.

## Step 1 - Get operator approval

The human operator must approve account creation and control the work-email inbox. The operator must select the scopes for an automation token. Do not submit registration or handle a credential without that approval.

## Step 2 - Register

Submit an API registration request with organization and operator details.

```http
POST https://api.verdictan.com/v1/auth/register
Content-Type: application/json
```

```json
{
  "org_name": "Acme Corp",
  "admin_email": "owner@acme.com",
  "admin_password": "CorrectHorseBatteryStaple!123",
  "admin_display_name": "Alice Smith"
}
```

If the request succeeds, it returns one of two non-authenticated states:

- `pending_approval`: wait for a platform administrator to approve the signup.
- `verification_required`: continue with the verification email.

These responses do not contain a session token, API token, or OAuth access token.

## Step 3 - Verify the email

The operator receives a verification email from Verdictan. Submit the verification token from that email link:

```http
POST https://api.verdictan.com/v1/auth/verify-email
Content-Type: application/json
```

```json
{
  "token": "<verification-token-from-email-link>"
}
```

The verification endpoint returns `{"result":"verified"}`. It does not sign the operator in and does not issue a bearer credential.

## Step 4 - Sign in and create an automation token

Have the human operator sign in at `https://console.verdictan.com/login`. When sign-in succeeds, it creates the browser session. For unattended access, the operator must create a scoped token from the API Tokens surface. The operator must transfer it through an approved secret channel.

Do not reuse an operator password, browser cookie, or CSRF value as the automation token. Do not reuse a provider API key or gateway runtime credential.

## Step 5 - Use the operator-created API token

Send the scoped token issued for this purpose as a bearer credential:

```http
GET https://api.verdictan.com/v1/events
Authorization: Bearer <operator-created-api-token>
```

- Give the token only the scopes necessary for the automation.
- Store and rotate it as a secret.
- Managed publication hostnames change gateway routing and locality. They do not change account registration or token issuance.
- On an unexpected `401`, stop using the token. Have the operator examine, rotate, or replace it.

## Related docs

- Agent onboarding guide: `https://docs.verdictan.com/docs/workflows/nodejs-integration/`
- Runtime request reference: `https://docs.verdictan.com/docs/reference/runtime-request-families/`
- API token guidance: `https://docs.verdictan.com/docs/guides/developer/api-key-management/`
- Managed endpoint locality: `https://docs.verdictan.com/docs/regions/overview/`
- Contact: `mailto:sales@verdictan.com`