# auth.md

## Amigo Treks agent access

Amigo Treks provides protected customer APIs for agents acting on behalf of an existing customer account. Agents receive a scoped OAuth 2.0 bearer access token and must send it in the HTTP **Authorization** header.

This service currently supports the **service_auth** flow: a pre-registered OAuth client starts the customer authorization flow, and the customer signs in before the authorization code is issued. ID-JAG identity assertions, anonymous registration, dynamic client registration, and a separate claim ceremony are not enabled.

## Step 1 — Discover the authentication metadata

Fetch these documents before making an authenticated API request:

- Protected Resource Metadata: https://www.amigotreks.com.np/.well-known/oauth-protected-resource
- Authorization Server Metadata: https://www.amigotreks.com.np/.well-known/oauth-authorization-server

The protected resource is the Amigo customer API. The authorization server metadata identifies the authorization and token endpoints, supported scopes, PKCE requirements, and the supported agent registration method.

## Step 2 — Register the OAuth client

OAuth clients must be pre-registered by Amigo Treks with an exact redirect URI. Contact Amigo Treks to receive a client ID and register the callback URL. There is no open dynamic client-registration endpoint.

The registration and authorization URI is https://www.amigotreks.com.np/oauth/authorize. Client registration is handled by Amigo Treks; this URI begins authorization for an already registered client.

## Step 3 — Start service-auth authorization

Create a high-entropy **state**, a high-entropy PKCE **code_verifier**, and its base64url-encoded SHA-256 **code_challenge**. Send the customer to the authorization endpoint with:

~~~http
GET https://www.amigotreks.com.np/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REGISTERED_REDIRECT_URI&response_type=code&scope=customer.read&state=STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256
~~~

The customer signs in on Amigo Treks. The registered callback receives a short-lived authorization **code** and the original **state**. Verify **state** before continuing.

## Step 4 — Exchange the authorization code

Exchange the code from the callback. The redirect URI and PKCE verifier must exactly match the authorization request:

~~~http
POST https://www.amigotreks.com.np/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTHORIZATION_CODE&client_id=CLIENT_ID&redirect_uri=REGISTERED_REDIRECT_URI&code_verifier=CODE_VERIFIER
~~~

The successful response contains an **access_token**, **token_type** **Bearer**, the granted **scope**, and an expiry when available. Treat the access token as a secret and never place it in a URL.

## Step 5 — Call the protected API

Send the access token in the header:

~~~http
GET https://www.amigotreks.com.np/api/customer/me
Authorization: Bearer ACCESS_TOKEN
~~~

Request only the narrowest scope needed. The same scope definitions are published in the OpenAPI OAuth security scheme:

- **customer.read** — read the customer's basic account information.
- **customer.profile** — access customer profile data.
- **customer.documents** — access customer travel documents.
- **customer.reviews** — access customer review data.
- **customer.payments** — access customer payment data.
- **customer.offers** — access customer offers and benefits.

## Step 6 — Revoke access

To revoke the current bearer session, send an authenticated **POST** request to https://www.amigotreks.com.np/api/customer/logout. This service does not expose a separate RFC 7009 token-revocation endpoint or a claim ceremony.

Do not ask a user to paste passwords, access tokens, payment details, passport information, or other sensitive data into an agent conversation. Use the Amigo Treks authorization page and secure API exchange instead.