Authentication

Every request to the Flora Codex API carries a credential in the Authorization header. There are two kinds, for two different callers:

A project API key identifies a project. Use it for server-side and scripted access. It is the simplest option and the one most integrations want.
A member access token identifies a person. Use it when a request acts on behalf of a signed-in member rather than a project.

You create both in the developer console at floracodex.com.

Project API key

Send the key in the Authorization header with the ApiKey scheme:

curl https://api.floracodex.com/v2/species -H "Authorization: ApiKey YOUR_KEY"

The key identifies the project it belongs to, which is what the API meters and rate-limits against. Keep it server-side; do not ship it in a browser or mobile client where it can be read.

Member access token

A member access token is a Bearer token, sent as:

curl https://api.floracodex.com/v2/species -H "Authorization: Bearer YOUR_TOKEN"

There are two ways to get one:

Personal access token. Create one in the console for your own account. Good for scripts and tools tied to you rather than to a project.
OAuth client credentials. For an application authenticating as itself. Create an OAuth client in the console, then exchange its credentials for a token at the token endpoint:

curl https://api.floracodex.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=fcc_YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

The response is a standard OAuth token:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 900
}

Send the access_token as the Bearer credential shown above. Cache it and reuse it across requests until it nears expiry (expires_in is in seconds, so 900 is 15 minutes); the token endpoint is itself rate-limited, so minting a fresh token per call will throttle you. Request a new one only as the old one runs out.

The interactive "Sign in with Flora Codex" flow, where a person approves a third-party app, does not exist yet. Today's OAuth is client credentials: an application authenticating as itself, not on behalf of another user.

How the versions differ

Version	Status	Credentials
v1	`Deprecated`	Takes the key or token in the `Authorization` header as shown above. Also accepts an `x-api-key` or `x-key` header, or a `key` or `token` query parameter. See the migration guide if you are moving off it.
v2	`Current`	Takes the key or token in the `Authorization` header only, as shown above.
v3	`Closed Preview`	Accepts a Bearer token only (a personal access token or an OAuth token). It does not accept API keys.

Missing or rejected credentials

A request with no credential, or one the API cannot verify, fails with a 401 and an auth/* code. A valid credential that lacks access to the resource fails with a 403. See the Errors guide for more about the errors envelope.