APIs
Endpoints, every sign-in method, keys and scopes, documentation, testing, versions.
An endpoint that runs a workflow
An API is a base path with one security policy; an endpoint binds one method and path to one workflow. What the consumer sends in the body is ready in the workflow as {{field}}; the step API response decides the status code and what they get back. You create an API with a POST endpoint, the workflow behind it, and call it.
A table as an API
Not every endpoint needs a workflow. You publish a table as an API in one go: list (with filters per column), get one row, add, update and delete — ordinary endpoints that inherit the API's policy. You choose which actions you offer, filter the list with a query string and add a row.
An endpoint that forwards to a connection
With Forward to connection you put an existing system behind your own API, without a workflow in between. The consumer sees your address and your security; Flow forwards the request with the key from the connection, which the consumer never sees. Path parameters such as {id} go along to the upstream path.
API keys and permissions (scopes)
An API key belongs to a department or team, opens only the APIs you tick, has only the permissions (scopes) you name and expires by itself. An endpoint can demand an extra permission. You issue a key without that permission and see 403, add it and see 200, and revoke the key: 401.
Sign in with HTTP Basic
Some systems can only send a user name and password: HTTP Basic. In Flow that is a client with a client_id and a client_secret, the same as for OAuth 2.0. You create a security policy with HTTP Basic, attach it to an API, create a client and call the API the way that system does.
Sign in with OAuth 2.0 (client credentials)
Applications that talk to each other often sign in with OAuth 2.0 client credentials: with a client_id and client_secret they fetch a short-lived token (one hour) from the token endpoint, and send it along as a bearer token. Flow's gateway is that token issuer itself. You create a policy with OAuth 2.0 and a required permission, a client with that permission, fetch a token and call the API with it.
A public API, without signing in
Sometimes anyone may ask for something: opening hours, a product catalogue, a status. A public API is off by default, because every call should be traceable to a consumer. An administrator switches it on for the workspace, with a reason that goes into the audit log. After that a policy Public opens an API without a key — and when the administrator switches it off again, every public API closes at once.
An API's description: OpenAPI and WSDL
Flow describes every API itself, from what you build: an OpenAPI description for REST and a WSDL for endpoints that also speak SOAP. By default only callers with a key or token for that API can read the description. With Public documentation anyone can read it — partners' developers build against it without an account — while calling it still requires signing in.
Test APIs: try any endpoint
Test APIs in the bar on the left is a workbench for all your endpoints: on the left the request and the answer, on the right the documentation Flow makes from the endpoint. You find an endpoint, sign in like a consumer, add query parameters and read the body and headers of the answer. Keys stay only in your session's memory.
A new version of an API
You do not change what consumers use under their hands. You put a new version next to the old one: the same name, version v2 and a base path of its own. An endpoint of v2 can reuse v1's logic through a facade — one workflow belongs to one endpoint, so one's security never leaks through the other. Once every consumer has moved, you switch v1 off.
Sign in with a webhook signature (HMAC)
Webhooks from payment providers, web shops and Git platforms (Stripe, Shopify, GitHub) do not sign in with a key, but sign every message: an HMAC over the body with a shared secret, in a header. Flow recalculates that signature itself. You create a policy with a webhook signature and see an unsigned message fail and a signed one get in.