# Flowie API authentication for agents

This document explains how an autonomous agent (or any programmatic client)
authenticates to the **Flowie Exchange API** — the machine-readable surface
behind get-flowie.com. It is written for the [WorkOS `auth.md`](https://workos.com/auth-md)
discovery pattern so agents can work out how to obtain and use credentials
without guessing.

Everything below is grounded in the published
[OpenAPI 3.1 description](https://get-flowie.com/openapi.json). Where a
capability is not yet offered, this document says so plainly rather than
advertising an endpoint that does not exist.

## Discover

An agent can discover Flowie's auth requirements from any of these, in order of
machine-friendliness:

1. **Protected-resource metadata (RFC 9728)** —
   [`/.well-known/oauth-protected-resource`](https://get-flowie.com/.well-known/oauth-protected-resource)
   declares the protected resource (the Exchange API), the accepted bearer
   method, and where to read the docs.
2. **OpenAPI security schemes** — [`/openapi.json`](https://get-flowie.com/openapi.json)
   `components.securitySchemes` describes `bearerAuth` and `apiKeyAuth`.
3. **This document** — [`/auth.md`](https://get-flowie.com/auth.md).
4. **A `401` response** — calling any protected route without a valid token
   returns `401 Unauthorized` with a JSON body such as
   `{"detail": "Missing authorization header"}`. Note: the Exchange API does
   **not** currently emit an RFC 6750 `WWW-Authenticate: Bearer` challenge
   header, so an agent cannot discover the auth scheme from the `401` alone —
   use one of the three resources above instead.

## Pick a method

The Exchange API accepts a **Bearer token** in the `Authorization` header. Two
kinds of token work — pick the one that fits your case:

| Method | Token | Best for |
| --- | --- | --- |
| **Exchange API key** (recommended for agents) | `flw_live_…` (production), `flw_test_…` (sandbox), plus `flw_plat_live_…` / `flw_wl_live_…` for platform / white-label keys | AI workflows, batch/idempotent operations, integrations, n8n / Make.com |
| **Flowie JWT** | RS256 JWT issued by Flowie's Auth0 tenant | Existing dashboard users and internal services already signed in to the platform |

## Register

Self-serve API-key issuance is **not** publicly available today. To obtain an
Exchange API key, request one from the Flowie team via
[get-flowie.com/contact](https://get-flowie.com/contact). Flowie JWTs are issued
automatically to authenticated platform users by Flowie's Auth0 tenant.

Note on the WorkOS `agent_auth` extensions: Flowie does **not** currently expose
an automated agent-registration endpoint (`register_uri`), OAuth Dynamic Client
Registration, or `identity_assertion` token exchange (e.g. `id-jag`,
`urn:ietf:params:oauth:token-type:id-jag`). Those are on the roadmap. Until they
ship, agents authenticate with an Exchange API key obtained as above. This
document is intentionally silent on machine `register_uri` / `claim_uri` /
`revocation_uri` values rather than advertising URIs that would not resolve.

## Claim

Once you have an Exchange API key, store it as a secret. It is a long-lived
credential — treat it like a password. No additional exchange or claim step is
required: the key **is** the bearer token.

## Use the credential

Send the token on every request:

```
Authorization: Bearer flw_live_…
```

- **Production base URL:** `https://back.p2p-flowie.com/exchange`
- **Sandbox base URL:** `https://back.flowie.ink/exchange`

Optional context headers:

- `X-Flowie-Organization-Id: <org>` — switch organization context.
- `X-Flowie-Company: <company>` — for platform keys acting on a managed tenant.

Example — resolve a company by VAT number (sandbox):

```
curl -s 'https://back.flowie.ink/exchange/v1/companies/resolve?vat=FR12345678901' \
  -H 'Authorization: Bearer flw_test_…'
```

Agents can also reach Flowie without an API key for **read-only** discovery: the
public [MCP server](https://get-flowie.com/mcp) (Streamable HTTP, no auth)
exposes `search_flowie`, `fetch_flowie_page`, and `get_flowie_overview` over
public get-flowie.com content.

## Errors

- **`401 Unauthorized`** — missing, malformed, expired, or revoked token. The
  body is JSON: `{"detail": "Missing authorization header"}` or
  `{"detail": "Invalid or revoked API key"}`. There is no `WWW-Authenticate`
  header today. Obtain or refresh a token and retry.
- **`403 Forbidden`** — the token is valid but lacks permission for the
  resource, or the wrong organization context was supplied. Check
  `X-Flowie-Organization-Id`.
- **`429 Too Many Requests`** — you are being rate-limited; back off and retry.

## Revocation

Exchange API keys can be revoked at any time. To rotate or revoke a key, contact
the Flowie team via [get-flowie.com/contact](https://get-flowie.com/contact). A
revoked key immediately returns `401` on every request. Flowie JWTs expire on
their own schedule and are re-issued through the platform's normal sign-in flow.

## References

- OpenAPI 3.1 spec: <https://get-flowie.com/openapi.json>
- Protected-resource metadata: <https://get-flowie.com/.well-known/oauth-protected-resource>
- Human API reference: <https://docs.get-flowie.com/reference>
- Developer hub: <https://get-flowie.com/developers>
- API catalog: <https://get-flowie.com/.well-known/api-catalog>