# Listings API auth.md

You are an agent. This service supports operator driven registration: discover → register → obtain a credential → call the API → handle rotation and revocation. Follow the steps in order. There is no OAuth authorization server and no token exchange; the credential is a static API key.

Agent audience: AI agents and automated clients calling the Listings API REST API at `https://listingsapi.com/api/v4` or the hosted MCP server at `https://listingsapi.com/mcp` on behalf of a business.

## Step 1 — Discover

Protected resource metadata lives at the conventional path:

```http
GET https://www.listingsapi.com/.well-known/oauth-protected-resource
```

It lists no `authorization_servers` because none exist. `bearer_methods_supported` is `["header"]`: you send the credential in the `Authorization` header. The API surface is described by the API catalog at `/.well-known/api-catalog` and the OpenAPI spec at `https://listingsapi.com/openapi.yaml`.

## Step 2 — Register

Registration is completed by a human operator, not by the agent. There is no programmatic self registration endpoint and no dynamic client registration.

1. The operator registers an account at the registration endpoint: `https://listingsapi.com/signup`
2. The operator provisions an API key at the credential provisioning endpoint: `https://listingsapi.com/dashboard`
3. The operator issues one API key per agent and hands the credential to the agent, so each credential can be revoked independently.

If you are an agent without a credential, stop here and ask your operator to complete registration and provision a key.

## Step 3 — Use the credential

Supported method: `api_key`. Send it in the `Authorization` header with the `API` scheme on every request:

```http
GET https://listingsapi.com/api/v4/locations
Authorization: API <your-api-key>
```

```bash
curl https://listingsapi.com/api/v4/locations \
  -H "Authorization: API $LISTINGSAPI_KEY"
```

The hosted MCP server uses the same credential and header:

```
claude mcp add --transport http listingsapi https://listingsapi.com/mcp --header "Authorization: API <your-api-key>"
```

A `401` response means the key is missing, malformed, or revoked. Do not retry with the same credential; report to your operator.

## Step 4 — Handle rotation and revocation

Keys are rotated and revoked by the operator in the dashboard at `https://listingsapi.com/dashboard`. Revocation is immediate: the revoked key stops working and other keys on the account keep working. If your requests start returning `401`, your credential was likely revoked; request a new one from your operator.

## References

- Protected resource metadata: https://www.listingsapi.com/.well-known/oauth-protected-resource
- API catalog: https://www.listingsapi.com/.well-known/api-catalog
- OpenAPI spec: https://listingsapi.com/openapi.yaml
- Documentation: https://docs.listingsapi.com/docs
- Agent skills index: https://www.listingsapi.com/.well-known/agent-skills/index.json