# visityour.biz Agent Authentication & Authorization Guide

<!-- metadata
title: visityour.biz Agent Authentication & Authorization Guide
description: Step-by-step documentation for AI agents to discover, register, claim credentials, and authenticate with the visityour.biz API using OAuth 2.0 and agent_auth specifications.
canonical: https://visityour.biz/auth.md
last-updated: 2026-08-30
-->

This guide explains how autonomous AI agents and automated software can discover, obtain, and manage authentication credentials to interact with the **visityour.biz** API and Model Context Protocol (MCP) servers.

## 1. Discovery

Agents can discover our OAuth 2.0 and agent authentication configuration through standard well-known endpoints:

- **Protected Resource Metadata (RFC 9728)**:
  `GET https://visityour.biz/.well-known/oauth-protected-resource`
- **Authorization Server Metadata (RFC 8414)**:
  `GET https://visityour.biz/.well-known/oauth-authorization-server`

The authorization server metadata includes the `agent_auth` configuration block:

```json
{
  "agent_auth": {
    "skill": "https://visityour.biz/auth.md",
    "register_uri": "https://visityour.biz/api/oauth/register",
    "claim_uri": "https://visityour.biz/api/oauth/claim",
    "revocation_uri": "https://visityour.biz/api/oauth/revoke",
    "identity_types_supported": [
      "anonymous",
      "identity_assertion"
    ]
  }
}
```

## 2. Choosing an Authentication Method

visityour.biz supports two primary mechanisms for agent onboarding:

1. **Anonymous / Instant Self-Serve**: Zero-friction onboarding for immediate read and search operations.
2. **OAuth 2.0 Client Credentials**: Long-lived API access for elevated rate limits, batch mutations, and enterprise directory queries.

## 3. Dynamic Agent Registration

To register dynamically, send a POST request to the `register_uri`:

```http
POST /api/oauth/register HTTP/1.1
Host: visityour.biz
Content-Type: application/json

{
  "client_name": "MyAutonomousAgent",
  "grant_types": ["client_credentials"],
  "response_types": ["token"],
  "scope": "read:businesses"
}
```

Response:
```json
{
  "client_id": "client_abc123",
  "client_secret": "secret_xyz789",
  "client_id_issued_at": 1704067200,
  "client_secret_expires_at": 0
}
```

## 4. Claiming Credentials

If using deferred claiming or verification links, verify your claim via `claim_uri`:

```http
POST /api/oauth/claim HTTP/1.1
Host: visityour.biz
Content-Type: application/json

{
  "claim_ticket": "ticket_987654321"
}
```

## 5. Obtaining and Using Bearer Tokens

Request an access token from the token endpoint:

```http
POST /api/oauth/token HTTP/1.1
Host: visityour.biz
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=client_abc123&client_secret=secret_xyz789&scope=read:businesses
```

Include the returned token in the `Authorization` header of every API request:

```http
GET /api/v1/businesses HTTP/1.1
Host: visityour.biz
Authorization: Bearer <access_token>
```

## 6. Token Revocation

When credentials are no longer needed, revoke them via `revocation_uri`:

```http
POST /api/oauth/revoke HTTP/1.1
Host: visityour.biz
Content-Type: application/x-www-form-urlencoded

token=<access_token>&token_type_hint=access_token
```

## 7. Error Handling & WWW-Authenticate Hints

Unauthenticated requests to protected endpoints return an HTTP `401 Unauthorized` status with a `WWW-Authenticate` header pointing to our protected resource metadata:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://visityour.biz/.well-known/oauth-protected-resource"
Content-Type: application/problem+json

{
  "type": "https://visityour.biz/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials are missing or invalid. Consult /auth.md."
}
```