# Auth.md

## Agent access

Request an agent key at [Developers](https://www.amigotrekking.com/developers). An administrator must approve it before use. The key-request response contains the numeric id (OAuth client_id) and the one-time key (OAuth client_secret). Keep the secret on your server.

This is an administrator-approved machine-to-machine registration flow, not the Auth.md user-claim or identity-assertion protocol. For the REST API, anonymous access, verified-email assertions, ID-JAGs and automated claim/revocation endpoints are not supported. Do not submit registration requests merely to test discovery: registration creates a pending credential request.

### Standalone registration flow

1. Submit a key request to `https://www.amigotrekking.com/api/agent/key-requests` with `Content-Type: application/json` and a JSON body containing `name`, `email` and `purpose`.
2. Save data.id as client_id and data.key as client_secret from the HTTP 201 response before waiting for administrator approval. The key is returned once, while its status is pending.
3. Exchange those credentials at `https://www.amigotrekking.com/api/agent/oauth/token` using the OAuth 2.0 client-credentials flow described below.

#### Register an approved agent

```http
POST /api/agent/key-requests HTTP/1.1
Host: www.amigotrekking.com
Content-Type: application/json

{"name":"YOUR_AGENT_NAME","email":"developer@example.com","purpose":"Read published travel content for trip planning."}
```

The service returns HTTP 201 with {"data":{"id":123,"status":"pending","key":"YOUR_ONE_TIME_AGENT_KEY"}}. Save the id and key immediately. After administrator approval, use those saved credentials with the token endpoint below. Name is limited to 120 characters; email is required; purpose must contain 20–2,000 characters.

## OAuth 2.0 client credentials

Discovery: [Authorization server metadata](https://www.amigotrekking.com/.well-known/oauth-authorization-server).
Site discovery: [Root protected resource metadata](https://www.amigotrekking.com/.well-known/oauth-protected-resource).
Resource: [Protected resource metadata](https://www.amigotrekking.com/.well-known/oauth-protected-resource/api/agent/v1).

POST https://www.amigotrekking.com/api/agent/oauth/token with Content-Type: application/x-www-form-urlencoded and HTTP Basic authentication using the client_id and client_secret (form-encode each before Base64 encoding id:secret). Send grant_type=client_credentials and an optional space-separated scope.

- trips.read: published trips, itineraries and published pricing (default).
- guides.read: published travel guides.
- departures.read: published departure dates.

Search spans all three collections and requires all three scopes. Unsupported scopes are rejected. The response contains access_token, token_type (Bearer), expires_in and scope. Tokens last at most 900 seconds, have no refresh token, and stop working when the approved key expires or is revoked. Obtain another token using client credentials when needed.

Send Authorization: Bearer ACCESS_TOKEN to https://www.amigotrekking.com/api/agent/v1. See the [OpenAPI description](https://www.amigotrekking.com/openapi.json) for each operation's scopes. No write scopes or customer-account access are granted.

## Existing agent keys and MCP

Existing approved keys still work as Authorization: Bearer YOUR_AGENT_API_KEY. Public MCP at https://www.amigotrekking.com/api/mcp/public requires no authentication, including consented enquiries and booking requests; the scoped OAuth tokens apply only to the content REST API. This is machine-to-machine OAuth, not an interactive customer login or ChatGPT OAuth authorization-code flow.

Customer login, accounts, private bookings, travel documents and payment records are not available to integrations. Travelers must use the Amigo website to manage their accounts.

## Claims

OAuth access tokens identify the approved agent client and granted read scopes. They do not identify or authorize a customer.

## Revocation

An administrator can revoke an approved agent key at https://www.amigotrekking.com/developers. Revocation immediately invalidates its API-key credentials and any OAuth tokens issued from it.