Authentication

every v1 endpoint requires an api key there are two ways to send it bearer token (recommended) send your key in the authorization header curl https //api mailfloss com/v1/organization \\ h "authorization bearer your api key" this is the preferred scheme for all new integrations it keeps your key out of urls, request logs, and browser history legacy api key query parameter (deprecated) prefer the bearer header for every integration the api key query parameter is deprecated, and the original legacy api that relied on it sunsets june 1, 2027 switching to bearer is a one line change (below) older integrations pass the key as a query parameter curl "https //api mailfloss com/v1/organization?api key=your api key" this still works on v1, but it's soft deprecated requests authenticated this way receive a deprecation true response header query parameters are easy to leak through server logs, proxies, and referrer headers migrating to bearer — move the key out of the query string and into the authorization header \# before — legacy api key query parameter curl "https //api mailfloss com/v1/organization?api key=your api key" \# after — bearer token (recommended) curl https //api mailfloss com/v1/organization \\ h "authorization bearer your api key" if you supply both a bearer token and an api key parameter on the same request, the bearer token wins getting and managing your key your api key is in the mailfloss dashboard under settings → api keys are scoped to your organization treat the key as a secret keep it server side never ship it in client side javascript, mobile apps, or anything a user can inspect don't commit it to source control load it from an environment variable or a secrets manager rotate it if you suspect exposure key formats today's full scope keys are prefixed mf live the api uses the key prefix to route to its validation strategy, which lets future key types arrive without any protocol change prefix meaning mf live full scope api key (current) mf rk restricted (scoped) key — coming in a future release mf oauth oauth issued token — coming in a future release you don't need to do anything to prepare for scoped keys or oauth; they'll be additive authentication errors a missing or rejected key returns a 401 with an authentication error { "error" { "code" "invalid api key", "message" "the provided api key is invalid ", "type" "authentication error", "request id" "req a1b2c3" } } common codes missing api key (no key supplied) and invalid api key (key rejected) see the errors guide for the full model