# Vidext auth.md

Vidext supports agentic registration for Vidext Operator through an email-required, user-claimed flow. Agents can register on behalf of an existing Vidext user, complete a one-time password claim ceremony, and receive a scoped bearer access token for the operator MCP endpoint.

## Discovery

- Protected resource metadata: [/.well-known/oauth-protected-resource](https://staging.vidext.com/.well-known/oauth-protected-resource)
- Authorization server metadata: [/.well-known/oauth-authorization-server](https://staging.vidext.com/.well-known/oauth-authorization-server)
- Registration endpoint: `https://staging.vidext.com/api/agent/auth`
- Claim endpoint: `https://staging.vidext.com/api/agent/auth/claim` (reserved for anonymous-start flows; email-required registrations skip it)
- Claim completion endpoint: `https://staging.vidext.com/api/agent/auth/claim/complete`
- Developer guide: [/developers](https://staging.vidext.com/developers)

## Supported Flow

Vidext currently supports only `identity_assertion` with `assertion_type: "verified_email"`.

Anonymous registration and ID-JAG provider assertions are not enabled. Do not request `api_key` credentials; Vidext issues only expiring `access_token` credentials for this flow.

## Scopes

- `mcp:operator` - call the Vidext Operator MCP tool for the selected workspace.

## Step 1 - Register

Ask the user for the email address attached to their Vidext account, then register with:

```http
POST /api/agent/auth
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "assertion": "user@example.com",
  "requested_credential_type": "access_token"
}
```

A successful registration emails the user a six-digit verification code and returns a claim token:

```json
{
  "registration_id": "reg_...",
  "registration_type": "email-verification",
  "claim_url": "https://staging.vidext.com/api/agent/auth/claim",
  "claim_token": "clm_...",
  "claim_token_expires": "2026-05-23T12:00:00.000Z",
  "post_claim_scopes": ["mcp:operator"]
}
```

The `claim_token` is returned once. Keep it only for the claim ceremony.

## Step 2 - Complete Claim

Ask the user to read the six-digit code from the Vidext email. Submit it with the claim token:

```http
POST /api/agent/auth/claim/complete
Content-Type: application/json

{
  "claim_token": "clm_...",
  "otp": "123456"
}
```

If the user belongs to multiple Vidext workspaces, the response is:

```json
{
  "error": "organization_selection_required",
  "organizations": [
    { "id": "org_...", "name": "Acme", "slug": "acme" }
  ]
}
```

Ask the user which workspace to use, then retry the same completion request with `organization_id` set to the chosen organization id.

On success, Vidext returns an access token:

```json
{
  "registration_id": "reg_...",
  "status": "claimed",
  "credential_type": "access_token",
  "credential": "vxt_agent_...",
  "credential_expires": "2026-05-30T12:00:00.000Z",
  "scopes": ["mcp:operator"]
}
```

## Step 3 - Use The Credential

Present the credential as a bearer token when calling the operator MCP endpoint:

```http
Authorization: Bearer vxt_agent_...
```

Access tokens expire after 7 days. If a token expires or an operator MCP call returns `401`, discard the credential and restart registration.

## Errors

| Code | Meaning |
| --- | --- |
| `unsupported_identity_type` | The requested registration type is not enabled. |
| `unsupported_assertion_type` | Only `verified_email` is accepted. |
| `unsupported_credential_type` | Only `access_token` is issued. |
| `email_delivery_failed` | Vidext could not send the verification code. |
| `claim_not_required` | Email-required registrations skip the claim-start endpoint. |
| `invalid_claim_token` | The claim token is unknown or expired. |
| `claim_expired` | The claim token is expired. Restart registration. |
| `otp_invalid` | The code did not match. Ask the user to re-read it. |
| `otp_expired` | The code expired. Restart registration. |
| `user_not_found` | The verified email does not belong to an existing Vidext user. |
| `organization_required` | The user has no active Vidext workspace. |
| `organization_selection_required` | The user must choose a workspace. |
| `organization_forbidden` | The chosen workspace is not available to this user. |
| `claimed_or_in_flight` | The claim is already being completed. |
| `rate_limited` | Back off and retry later. |