# GST Cranes Auth

Public read endpoints and public pages can be fetched without an API token.

## Discover

- Marketplace pages, Crane Wiki atlas pages, sitemaps, llms.txt, the API catalog, and the public companies OpenAPI are public.
- The public OpenAPI currently covers public company and fleet-record data only.

## Pick a method

- Public read: no credential required.
- Browser session: required for account, listing, wanted-ad, credits, saved alerts, inbox, and promotion actions.
- Public OAuth/API-key program: not available yet.

## Agent auth metadata

GST Cranes exposes browser-session handoff metadata for agents. It does not mint API tokens and it does not convert private website actions into public API calls.

- oauth-protected-resource: https://gstcranes.com/.well-known/oauth-protected-resource describes private browser-session protected actions.
- oauth-authorization-server: https://gstcranes.com/.well-known/oauth-authorization-server describes the browser sign-in handoff and agent_auth block.
- agent_auth: browser session handoff only. Agents should read https://gstcranes.com/agent/auth for machine-readable handoff metadata, then send users to the relevant GST Cranes page for authenticated listing, wanted-ad, credits, promotion, saved-alert, inbox, or account actions.
- register_uri: https://gstcranes.com/login. Users register or sign in through the GST Cranes browser UI.

## agent_auth

```yaml
agent_auth:
  status: browser_session_handoff_only
  public_read: true
  oauth-protected-resource: https://gstcranes.com/.well-known/oauth-protected-resource
  oauth-authorization-server: https://gstcranes.com/.well-known/oauth-authorization-server
  agent_auth_endpoint: https://gstcranes.com/agent/auth
  register_uri: https://gstcranes.com/login
  resource_metadata: https://gstcranes.com/.well-known/oauth-protected-resource
  WWW-Authenticate: Bearer resource_metadata="https://gstcranes.com/.well-known/oauth-protected-resource"
  supported_public_resources:
    - https://gstcranes.com/.well-known/openapi.json
    - https://gstcranes.com/.well-known/api-catalog
    - https://gstcranes.com/.well-known/mcp
    - https://gstcranes.com/ask
    - https://gstcranes.com/agent/auth
```

The `WWW-Authenticate` hint above is for private browser-session actions. Public read endpoints stay zero-auth and private actions continue through the signed-in website.

Machine-readable browser-session handoff metadata is available at https://gstcranes.com/agent/auth. It does not mint tokens and does not represent a public API-key program.

## Zero-auth first API call

Public company and Crane Wiki reads do not require a token. No Authorization header is required for public reads.

1. Discover the API:

```bash
curl https://gstcranes.com/.well-known/openapi.json
```

2. Fetch public company records:

```bash
curl https://gstcranes.com/api/companies?country=DE
```

3. Batch-fetch public company records by slug:

```bash
curl -X POST https://gstcranes.com/api/companies/batch \
  -H 'content-type: application/json' \
  -H 'GST-API-Version: 2026-07-06' \
  --data '{"slugs":["bms-heavy-cranes"]}'
```

If the action is not a public read, hand the user to the signed-in GST Cranes browser UI instead of requesting a token.

## Authentication walkthrough

| Scenario | Authentication | Agent action |
| --- | --- | --- |
| Read public company records | No API key required | Fetch the public endpoint directly. |
| Read OpenAPI, llms.txt, API catalog, MCP, A2A, or Agent Skills metadata | No API key required | Fetch the public discovery URL directly. |
| Search public Crane Wiki/company data through /ask | No API key required | POST a public read-only question. |
| Publish a listing, post a wanted ad, spend credits, manage saved alerts, open inbox, or change billing | Browser session required | Send the user to the signed-in GST Cranes web UI. |

Authorization: Bearer is not used for public reads. A `401 sign_in_required`, sign-in redirect, or browser-session requirement means the agent should stop API automation and hand the user to the website.

## Register

There is no self-serve API-key registration endpoint. Users register or sign in through the normal GST Cranes browser UI when they need to perform an authenticated action.

## Claim

Company updates, listing ownership, account state, billing, and credits are claimed through the signed-in web application, not through a public agent API.

## Use credential

Agents can fetch public resources without credentials. If the user is signed in inside the browser, the website manages the session and form submission. Do not ask users to paste private session cookies or tokens into an agent.

## Errors

Public JSON APIs return machine-readable errors with `error.code`, `error.message`, and `error.resolution`. A `401` or sign-in redirect means the action must continue in the browser UI.

## Revocation

There are no public API tokens to revoke. Browser sessions and account access are controlled through the GST Cranes web application.

## User actions

- Listing creation, wanted-ad publishing, promotion purchases, saved alerts, inbox, account, and billing flows require the normal GST Cranes website sign-in session.
- No public OAuth, API-key, or agent-native delegated authorization program is available yet.

## Agent guidance

- Do not submit forms, spend credits, or infer private account state without an authenticated user action in the browser.
- If an action requires login, send the user to the relevant GST Cranes page rather than trying to call a private endpoint.