# Vignette ID auth.md

> How AI agents authenticate with Vignette ID. The public catalogue needs no credential; issuing a vignette needs a static partner API key sent as a bearer token, obtained by applying through the partner form. There is no OAuth authorization server, so this document is self-contained.

Canonical HTML page: https://e-vignettes.eu/developers

- **Audience:** AI agents and the developers integrating them
- **Public surfaces:** https://e-vignettes.eu/api/v1 and https://e-vignettes.eu/mcp — no credential required
- **Authenticated surfaces:** the partner API on vignette.id, including https://api.vignette.id/mcp (sandbox https://sandbox-api.vignette.id/mcp)
- **Supported method:** static partner API key, sent as Authorization: Bearer YOUR_PARTNER_API_KEY
- **Registration:** https://e-vignettes.eu/partner — a human application, reviewed by the team
- **Automated client registration:** not supported; no endpoint issues credentials
- **OAuth 2.0 and OpenID Connect:** not supported; no authorization server exists
- **Contact:** work@vignette.id

## Who this document is for

This document is addressed to AI agents and to the developers integrating them. It describes every way of authenticating with Vignette ID and nothing else; product guidance lives in the agent brief at https://e-vignettes.eu/agents.md and the developer portal at https://e-vignettes.eu/developers.

Vignette ID runs two distinct surfaces, and confusing them is the usual reason an integration fails. The public catalogue on e-vignettes.eu answers questions about European motorway tolls and needs no credential whatsoever. The partner API on vignette.id issues real vignettes, takes money and needs a partner API key. Read the tier that matches what you are trying to do.

Most agent work here falls in the first tier. Read it before assuming you need to authenticate at all.

## Tier 1: the public surfaces, which need no credential

Prices, country toll rules and the product catalogue are public, read-only and unauthenticated. There is no key to obtain, no account to create and no header to send. CORS is open, so a browser-based agent can call these directly.

Requests are rate limited per IP address rather than per client: 240 requests per 60 seconds across the REST API and 120 per 60 seconds on the MCP endpoint. Every response carries RateLimit-Policy and RateLimit, so read them and self-throttle instead of discovering the limit with a 429. Going over returns 429 with Retry-After in seconds.

Failures are always JSON, never an HTML error page, with a stable error.code to branch on: not_found, invalid_parameter, method_not_allowed, rate_limited, upstream_unavailable and internal_error. None of them mean you are missing a credential, because none of these endpoints accept one.

- Public read API, no authentication: https://e-vignettes.eu/api/v1/countries, https://e-vignettes.eu/api/v1/countries/{code} and https://e-vignettes.eu/api/v1/products. Machine description: https://e-vignettes.eu/openapi.json
- This site's own MCP server, no authentication: https://e-vignettes.eu/mcp over Streamable HTTP, exposing list_countries, get_country, list_products and read_page. Manifest: https://e-vignettes.eu/.well-known/mcp.json
- Markdown of any page, at the page's own URL, by sending Accept: text/markdown. Also unauthenticated.
- An Authorization header sent to any of these is ignored. Do not send a partner key to e-vignettes.eu: it buys you nothing and leaks the credential to a host that has no use for it.

## Tier 2: the partner surfaces, which need an API key

Creating an order, validating a vehicle, cancelling or modifying an order and receiving webhooks all run on the authenticated partner API, on a different host from the public catalogue. This is the only tier that can actually issue a vignette. The same credential authenticates the REST partner API and the partner MCP server.

One authentication method is supported: a static partner API key, sent as an HTTP Authorization header of the form Bearer followed by a single space and the key. There is no other accepted method. The key is not an OAuth access token: it is long-lived, it does not expire on a schedule, there is no refresh step and nothing is exchanged for it. It is rotated and revoked by hand in the Partner Panel.

Sandbox and production are separate environments with separate keys, and a key from one is rejected by the other. Build against the sandbox first: the full order lifecycle, including webhook events and cancellations, works there without touching real payments or government systems.

The partner MCP server exposes 11 tools: get_products, get_products_status, get_users, get_user_orders, validate_vehicle, create_order, get_orders, get_order, get_order_status, cancel_pending_order, cancel_deferred_order. A typical purchase is get_products, then validate_vehicle, then create_order, then get_order_status.

- Production MCP endpoint: https://api.vignette.id/mcp
- Sandbox MCP endpoint: https://sandbox-api.vignette.id/mcp
- Credential type: static API key, issued per partner per environment.
- How it is sent: the request header Authorization: Bearer YOUR_PARTNER_API_KEY. Header transport only; the key never goes in a query string or a request body.
- Where the issued key is read: Partner Panel, section For Developers.
- REST and MCP reference documentation: https://docs.vgnt.app/wiki/mcp-server

## How a credential is obtained

Registration is a human step, not an API call. Apply through the partner form at https://e-vignettes.eu/partner. The team replies, and a sandbox key follows so you can integrate before anything is signed. A cooperation agreement with PD Business Services FZ LLC is concluded before production keys are issued, together with the commission terms.

Once the partner account exists, the key itself is read from the Partner Panel, section For Developers. Keys are rotated there as well.

There is no automated or dynamic client registration today. No endpoint issues a credential to a caller that presents one, and none is planned to appear without being documented here first. An agent cannot obtain a key on its own: surface the partner form to your human operator and let a person apply. Do not attempt to register, guess, enumerate or brute-force a credential.

Questions about keys, sandbox access and commission terms go to work@vignette.id.

## What Vignette ID deliberately does not publish

Vignette ID operates no OAuth 2.0 authorization server and no OpenID Connect provider, and none of its APIs is an OAuth protected resource. There is therefore nothing of that kind to discover here: no authorization endpoint, no token endpoint, no key set for verifying tokens, no scopes, no refresh tokens, no consent screen and no dynamic client registration.

Discovery documents describing any of that are intentionally absent rather than merely missing. Publishing them to satisfy a readiness scanner would point agents at endpoints that do not answer, which is worse for an agent than an honest absence. This document is the complete and self-contained description of authentication here, exactly as the auth.md specification prescribes for a service without OAuth metadata.

If you encounter a document elsewhere that advertises OAuth endpoints for Vignette ID, it did not come from us. The credential mechanisms described on this page are the only ones that exist.

## If you have no credential

This is the expected state for a general-purpose agent, and it is not an error. Almost everything an agent is asked about vignettes can be answered without one.

- To answer what a vignette costs, which roads are tolled, how fast a vignette activates or what a fine is: use the tier 1 endpoints above. No key, no sign-up.
- To let a person buy a vignette: send them to https://vignette.id/products and let them complete the purchase themselves. Do not attempt to order on their behalf without a key.
- To build software that sells vignettes: apply at https://e-vignettes.eu/partner.
- A 401 or 403 from a partner host means the key is missing, malformed or wrong for that environment. It is not a transient failure: retrying it unchanged will fail identically, so stop and report it.

## Handling the credential safely

A partner key authorises real purchases, so treat it as a payment credential rather than as configuration.

- Send it only to the partner hosts named above. No other host, including this one, ever needs it.
- Keep it out of logs, traces, prompts, tool call transcripts and anything shown back to an end user.
- Never place it in a URL, a query parameter or a redirect target; the Authorization header is the only supported transport.
- Use the sandbox key for everything that is not a real order, and keep the production key out of development environments.
- Rotate in the Partner Panel if a key is exposed, and tell us at work@vignette.id if you suspect it was used by someone else.

## Getting help

Integration, keys, sandbox access and commission terms: work@vignette.id. Questions about an individual order, a refund or a cancellation: seller@vignette.id.