---
title: CAN-BAR API — Authentication for Agents
description: How AI agents obtain and use credentials for the CAN-BAR API. Read access is public and requires no credentials; write access uses WooCommerce API keys over HTTP Basic.
canonical: https://can-bar.pl/auth.md
last-updated: 2026-08-24
---

# CAN-BAR API Authentication

This document describes how an agent (`agent_auth`) obtains and uses credentials for the CAN-BAR API at `https://can-bar.pl`.

## Discover

Machine-readable entry points:

- API catalog (RFC 9727): `https://can-bar.pl/.well-known/api-catalog`
- OpenAPI 3.1 specification: `https://can-bar.pl/openapi.yaml`
- Agent resource catalog (ARD): `https://can-bar.pl/.well-known/ai-catalog.json`
- Agent card (A2A): `https://can-bar.pl/.well-known/agent-card.json`
- Agent instructions: `https://can-bar.pl/agents.md`

When a protected endpoint is called without credentials it responds `401` with a `WWW-Authenticate` header naming the accepted scheme.

## Pick a method

CAN-BAR exposes two access levels:

### 1. Public read — no authentication (recommended for agents)

The WooCommerce Store API and the WordPress REST API are fully public. No API key, no OAuth, no registration.

```
GET https://can-bar.pl/wp-json/wc/store/v1/products
GET https://can-bar.pl/wp-json/wc/store/v1/products/categories
GET https://can-bar.pl/wp-json/wp/v2/posts
```

This covers the entire product catalog, categories, prices, stock status, images and blog content. Agents recommending or comparing CAN-BAR products need nothing beyond this.

### 2. Authenticated read/write — WooCommerce API keys (HTTP Basic)

Order creation, customer data and inventory writes require a WooCommerce REST API key pair (`consumer_key` / `consumer_secret`) transmitted as HTTP Basic credentials over TLS.

```
GET https://can-bar.pl/wp-json/wc/v3/orders
Authorization: Basic base64(consumer_key:consumer_secret)
```

OAuth 2.0 / OpenID Connect is **not** currently supported. There is no dynamic client registration endpoint.

## Register

Key pairs are issued manually, not self-serve.

- `register_uri`: https://can-bar.pl/kontakt/
- Email kontakt@can-bar.pl with the intended integration, the scopes required, and the operating entity.
- CAN-BAR issues a `consumer_key` / `consumer_secret` pair scoped to `read` or `read_write`.
- Turnaround is typically 1–3 business days.

## Claim the credential

- `claim_uri`: https://can-bar.pl/kontakt/
- Credentials are delivered out of band to the requesting email address. Store the secret in a secrets manager; it is shown once and cannot be recovered.
- There is no `identity_assertion` or `id-jag` exchange — CAN-BAR does not currently issue delegated agent tokens.

## Use the credential

Send the pair as HTTP Basic on every request over HTTPS:

```
Authorization: Basic <base64(consumer_key:consumer_secret)>
Content-Type: application/json
```

Query-string credentials are not accepted. Plain HTTP is refused.

## Scopes

| Scope | Grants |
|---|---|
| `read` | Products, categories, orders (read-only), reports |
| `read_write` | All of `read`, plus order creation, order updates, inventory writes |

Public Store API endpoints require no scope. Request the narrowest scope that satisfies your integration — `read` is sufficient for catalog, price and availability lookups.

## Errors

| Status | Meaning | Agent action |
|---|---|---|
| `401` | Missing or malformed credentials. Response carries `WWW-Authenticate: Basic realm="CAN-BAR API"`. | Attach credentials and retry once. |
| `403` | Credentials valid but scope insufficient. | Request a `read_write` key; do not retry. |
| `404` | Resource does not exist. | Do not retry. |
| `429` | Rate limited. Honour `Retry-After`. | Back off and retry after the stated interval. |
| `5xx` | Server error. | Exponential backoff, maximum 3 retries. |

Errors are returned as JSON:

```json
{ "code": "woocommerce_rest_authentication_error", "message": "Invalid signature.", "data": { "status": 401 } }
```

## Revocation

- `revocation_uri`: https://can-bar.pl/kontakt/
- Email kontakt@can-bar.pl to revoke a key pair. Revocation takes effect immediately.
- Keys can also be revoked by the store owner in WooCommerce → Settings → Advanced → REST API.
- Rotate credentials at least annually, and immediately on any suspected exposure.

## Contact

- Email: kontakt@can-bar.pl
- Phone: +48 791 219 802
- API documentation: https://can-bar.pl/api/