# auth.md — How agents authenticate with DTFOOD

DTFOOD is the B2B marketplace and network for the German–Turkish food industry.
This document describes how an autonomous agent obtains and uses credentials for
the DTFOOD public API.

## Audience

- Buyer-side and research agents that read listings, trade fairs, news and company profiles.
- Partner agents acting on behalf of a registered DTFOOD member company.

## Base URLs

- API base: `https://dtfood.org/api/v1`
- Service description: `https://dtfood.org/openapi.json`
- API catalog: `https://dtfood.org/.well-known/api-catalog`

## Registration endpoint

Agent clients register via OAuth 2.1 Dynamic Client Registration (RFC 7591):

```
POST https://dtfood.org/oauth/register
Content-Type: application/json

{
  "client_name": "Example Buyer Agent",
  "redirect_uris": ["https://example.com/oauth/callback"],
  "grant_types": ["authorization_code", "client_credentials"],
  "token_endpoint_auth_method": "none"
}
```

The response contains `client_id` (and `client_secret` for confidential clients).

Human path: a member company can also request API credentials at
`https://dtfood.org/kontakt`.

## Supported methods

| Method | Use case | Endpoint |
| --- | --- | --- |
| OAuth 2.1 authorization code + PKCE | Agent acting for a signed-in DTFOOD user | `https://dtfood.org/oauth/authorize` → `https://dtfood.org/oauth/token` |
| OAuth 2.1 client credentials | Unattended read-only access to public catalog data | `https://dtfood.org/oauth/token` |
| Anonymous | Public read endpoints marked `security: []` in the OpenAPI document | — |

Authorization server metadata: `https://dtfood.org/.well-known/oauth-authorization-server`
Protected resource metadata: `https://dtfood.org/.well-known/oauth-protected-resource`

## Scopes

- `catalog:read` — listings, products, companies, trade fairs
- `content:read` — news, standpunkte, podcasts, videos
- `leads:write` — submit inquiries and contact requests
- `orders:write` — create quote requests and bookings

## Using credentials

Send the access token in the `Authorization` header:

```
GET /api/v1/listings HTTP/1.1
Host: dtfood.org
Authorization: Bearer <access_token>
Accept: application/json
```

Tokens are short-lived (1 hour). Refresh with the `refresh_token` grant.
Never place tokens in query strings.

## Rate limits

- Anonymous: 60 requests/minute per IP
- Authenticated agents: 600 requests/minute per client
- `429 Too Many Requests` responses include a `Retry-After` header.

## Metered endpoints

Some endpoints are priced per call. They answer `HTTP 402 Payment Required`
with an `accepts[]` payload per the x402 protocol; see
`https://dtfood.org/.well-known/x402.json` and the `x-payment-info` metadata in
the OpenAPI document.

## Contact

Security and API support: info@dtfood.org