Zum Inhalt springen
Fipeo

Fipeo for developers

Authentication

Early access. The API, the webhooks and the widget are switched off for most accounts while we try them with the first schools and agencies. This documentation is public so you can plan your integration: write to [email protected] and we switch it on for you.

There are two ways to authenticate. Both send a bearer token in the Authorization header and give exactly the same access: use an API key for your own scripts, Zapier or Make, and OAuth 2.0 when a product you use only speaks OAuth.

API keys

  • Created in Integrations › API keys by the owner or an administrator of the agency, or by the main account of the school.
  • They look like fpk_ followed by about 43 characters. The key is shown once; Fipeo only keeps its SHA-256 hash and its first 12 characters, so you can recognise it.
  • Send it as Authorization: Bearer fpk_…, never in the URL. The API does not use cookies.
  • Optional expiry date, up to 2 years. You can revoke a key at any moment and it stops working at once.
  • A key also stops working if the account is suspended, or if the person who created it leaves the agency or stops being an administrator: create keys with an account that will stay.
  • Each key has a usage log (requests and errors per day and route, 30 days) in the panel.

Scopes

Each key or OAuth application has a list of scopes. A route needs its scope; without it the answer is 403 insufficient_scope. A school can only have bookings:read.

ScopeForRoutes
(none)agencies and schoolsGET /me
catalog:readagenciesGET /schools, GET /courses
quotes:readagenciesGET /quotes, GET /quotes/{id}
bookings:readagencies and schoolsGET /bookings (agency: your bookings; school: your inbox), GET /bookings/{reference} (agencies)
students:readagenciesGET /students, GET /students/{id}
students:writeagenciesPOST /students

Data processing agreement: when it is required, students and quotes answer 403 dpa_required until the owner of the account accepts it in the panel, the same as in the panel itself.

OAuth 2.0 client credentials

For software that authenticates with OAuth (CRMs, iPaaS, booking systems). In Integrations › OAuth applications create an application with a name and its scopes. You get a client ID (fpc_…) and a client secret (fps_…, shown once). You can have up to 5 active applications.

Ask for a token

Authenticate the client with HTTP Basic, or with client_id and client_secret in the body (form-urlencoded or JSON), never both. scope is optional: a subset of the application’s scopes separated by spaces; without it you get all of them.

HTTP Basic
curl https://fipeo.net/api/public/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="bookings:read students:read"
Credentials in the body
curl https://fipeo.net/api/public/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"
200 OK
{ "access_token": "fpt_…", "token_type": "Bearer", "expires_in": 3600, "scope": "bookings:read students:read" }

Use it

bash
curl https://fipeo.net/api/public/v1/bookings \
  -H "Authorization: Bearer $ACCESS_TOKEN"
  • The token lasts one hour (expires_in: 3600). There is no refresh token: ask for a new one when it expires. Reuse it until then: an application can have at most 20 active tokens.
  • It has the same limits as a key (counted per application), the same scopes and the same answers.
  • Errors follow RFC 6749 §5.2: 400 with invalid_request, unsupported_grant_type or invalid_scope; 401 invalid_client (with WWW-Authenticate: Basic if you used Basic). Fipeo never says why a client is invalid.

Revoke and rotate

Revoke a token (RFC 7009)
curl https://fipeo.net/api/public/v1/oauth/revoke \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d token="$ACCESS_TOKEN"

In the panel you can also give the application a new secret and keep the old one valid for 0 to 24 hours while you deploy it (0 stops it at once and revokes the tokens), revoke all its tokens, or revoke the whole application.

Who sees what

  • A key only sees its own organization. Anything else, even if it exists, answers 404 not_found.
  • Routes for agencies called with a school key answer 403 insufficient_scope (a school key can only have bookings:read); GET /bookings/{reference} answers 404.
  • What comes out is a closed list of fields: commissions, net prices, the school price of a quote, payments and internal notes never come out, and a second filter removes any field that could carry them.