Register a partner app with OAuth and manage installed apps

An OAuth app lets other Flowella organisations connect your product to their account without sharing API keys. Each organisation approves your app on a consent screen and can revoke it at any time. This page shows partners how to register an app and use OAuth, and shows customers how to review and revoke the apps they have installed. For your own scripts and integrations, an API key is simpler.

How it works

Flowella supports three OAuth grants: authorisation code with PKCE for customers’ organisations, client credentials for your own organisation, and refresh tokens. The sequence shows how a customer installs your app with the authorisation code grant.

Before you start

You need the Owner or Admin role in the organisation that will own the app. Other roles can see Developer apps in the menu, but the list does not load for them.
Your app needs a callback address (redirect URI) that can receive the authorisation code.
Your app must send a state value and a PKCE code_challenge made with S256 on every authorisation request.

Register an app

Open Developer apps

Go to Settings, then select Developer apps in the Developer group.

Start a new app

Select Create app. The Create developer app dialog opens.

Name the app

In App name, enter the name customers know your product by, up to 120 characters, for example Acme CRM connector.

Add redirect URIs

In Redirect URIs, enter each callback address on its own line, up to 20. During authorisation, the redirect_uri your app sends must match one of these exactly.

Choose scopes

Under Scopes, the read scopes are ticked for you. Tick any other scope your app needs and untick the ones it does not. These are the most your app can ever request. See Scopes.

Create the app and copy the secret

Select Create app. The Save your client secret dialog shows the client secret, which starts with flc_. Select Copy, store the secret on your server, then select Done.

Flowella shows the client secret only once, and you cannot reset it. If you lose it, you have to delete the app and register a new one, and every organisation that uses your app must approve the new one.

You cannot change an app’s name, redirect URIs or scopes after you create it. To change them, register a new app. The Developer apps list shows each app’s Name, Client ID (it starts with floa_), Redirect URIs and Created date, with a Delete button under Actions.

Send a customer through authorisation

Send the customer’s browser to the authorise endpoint on the Flowella app host:

https://app.flowella.io/api/oauth/authorize?response_type=code&client_id=floa_xxxx&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=messages%3Aread%20contacts%3Aread&state=RANDOM_STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Parameter	Required	Value
`response_type`	Yes	`code`
`client_id`	Yes	Your app’s client ID.
`redirect_uri`	Yes	One of the app’s registered redirect URIs, exactly.
`state`	Yes	A random value your app checks when the customer comes back.
`code_challenge`	Yes	The base64url-encoded SHA-256 hash of a random `code_verifier` your app keeps.
`code_challenge_method`	No	`S256`, the only supported method and the default.
`scope`	No	Scopes separated by spaces, all within the app’s scopes. Without it, the app gets only the read scopes it is allowed.
`publicOrgId`	No	The six-digit organisation number from the customer’s Flowella web address. Without it, Flowella uses the organisation the person is currently working in.

If the request is invalid, Flowella shows an error instead of the consent screen and does not redirect. This happens, for example, when the redirect_uri does not match or a scope is not allowed.

What the customer sees

If the person is not signed in, Flowella asks them to sign in first.
The person must be an Owner or Admin of the organisation. Anyone else sees the error Owner or admin role required to authorize apps.
The Authorize app screen shows your Client ID: and the Requested scopes:. If your app did not send a scope, it says This app will receive its default allowed scopes.
The person selects Allow access or Deny.

Allow access sends the browser to your redirect_uri with code and state in the query string. The code is valid for 10 minutes and works once. Deny sends the browser to your redirect_uri with error=access_denied, an error_description and your state.

Exchange the code for tokens

Your server exchanges the code at the token endpoint. Authenticate with your client ID and secret, either with HTTP Basic authentication or as client_id and client_secret in the body. The body can be form-encoded or JSON.

curl -X POST "https://app.flowella.io/api/oauth/token" \
  -u "$FLOWELLA_CLIENT_ID:$FLOWELLA_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://example.com/oauth/callback" \
  -d code_verifier="$CODE_VERIFIER"

The response contains the tokens:

{
  "access_token": "fla_xxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "flr_xxxxxxxxxxxxxxxx",
  "scope": "messages:read contacts:read"
}

Token	Starts with	Valid for
Access token	`fla_`	1 hour
Refresh token	`flr_`	30 days, and only until it is used once

The token endpoint accepts 30 requests a minute for each client ID and IP address. Above that, it returns 429 with a Retry-After header.

Call the API

Send the access token as a bearer token, exactly like an API key:

Authorization: Bearer fla_xxxxxxxxxxxxxxxx

The token works only for the organisation that approved it, and only for the scopes it was granted. A request outside those scopes returns 403 INSUFFICIENT_SCOPE. Each access token has its own rate limit. See the API introduction.

POST /v1/templates/send accepts API keys only and refuses OAuth access tokens with 401.

Refresh an access token

Before the access token expires, request a new one with grant_type=refresh_token, the refresh_token and your client authentication. The response has a new access token and a new refresh token, and the old refresh token stops working. If someone presents a refresh token that was already used, Flowella revokes every token issued from that authorisation, and the customer has to approve your app again.

Access your own organisation

To call the API for the organisation that owns the app, use grant_type=client_credentials with your client authentication and an optional scope. You get an access token without a refresh token. Your app then appears under Installed apps in your own organisation.

Revoke or inspect a token

Endpoint	What it does
`POST https://app.flowella.io/api/oauth/revoke`	Revokes the `token` you send, together with every token issued with it.
`POST https://app.flowella.io/api/oauth/introspect`	Returns whether the `token` is `active`, with its `scope`, `client_id`, `organization_id` and expiry time.

Both endpoints need your client authentication. The discovery document at https://app.flowella.io/.well-known/oauth-authorization-server lists every endpoint and supported option.

Review and revoke installed apps

Customers manage the apps they have approved under Installed apps. You need the Owner or Admin role. The list shows:

Column	What it shows
App	The app’s name, with its client ID below.
Scopes	The scopes the app was granted.
Installed	When the app was first approved.
Actions	Revoke, or a Revoked badge.

To revoke an app:

Go to Settings, then select Installed apps in the Developer group.
Select Revoke on the app’s row.
Confirm the prompt Revoke this install? Existing tokens stop working.

The app’s tokens stop working at once, and it cannot refresh them. The row stays in the list with a Revoked badge. To give the app access again, an Owner or Admin approves it again on the consent screen.

Revoking your own app in your own organisation does not stop the client credentials grant: the app can request a new token, which turns the install back on. To cut off your own app completely, delete it under Developer apps.

Delete an app

In Developer apps, select Delete on the app’s row and confirm Delete this app and its tokens? Flowella removes the app, its install in every organisation that approved it, and all its tokens. This cannot be undone.

Troubleshooting

Could not load developer apps or Could not load installed apps

Only Owners and Admins can view these screens. Ask an Owner or Admin to manage the app for you. Roles can’t be changed in the app: see Change someone’s role.

Redirect URI mismatch

The redirect_uri in the request must match one of the app’s registered redirect URIs exactly, including the scheme, path and any trailing slash. The same value must be sent again when you exchange the code. You cannot edit an app’s redirect URIs, so register a new app if you need a different one.

invalid_scope

A requested scope is misspelt or is not one of the app’s scopes. Request only scopes you ticked when you registered the app.

Owner or admin role required to authorize apps

The person approving the app is not an Owner or Admin of the organisation. Ask an Owner or Admin to complete the authorisation.

The code exchange fails

The messages Authorization code expired and Authorization code already used mean you need to start the authorisation again: codes last 10 minutes and work once. PKCE verification failed means the code_verifier does not match the code_challenge you sent.

API introduction

Authentication, scopes, rate limits and errors.

Developer hub

Recent API requests, quickstarts and the API sandbox.

API keys

Simpler access for your own scripts and integrations.

Webhooks reference

React to events in the organisations that install your app.

Get Started

Essentials

Using the App

Settings

Meta & WhatsApp Setup

HubSpot Integration

Flows & Campaigns

API Reference

Troubleshooting

Changelog

Register a partner app with OAuth and manage installed apps

How it works

Before you start

Register an app

Send a customer through authorisation

What the customer sees

Exchange the code for tokens

Call the API

Refresh an access token

Access your own organisation

Revoke or inspect a token

Review and revoke installed apps

Delete an app

Troubleshooting

API introduction

Developer hub

API keys

Webhooks reference

​How it works

​Before you start

​Register an app

​Send a customer through authorisation

​What the customer sees

​Exchange the code for tokens

​Call the API

​Refresh an access token

​Access your own organisation

​Revoke or inspect a token

​Review and revoke installed apps

​Delete an app

​Troubleshooting

​Related

API introduction

Developer hub

API keys

Webhooks reference

How it works

Before you start

Register an app

Send a customer through authorisation

What the customer sees

Exchange the code for tokens

Call the API

Refresh an access token

Access your own organisation

Revoke or inspect a token

Review and revoke installed apps

Delete an app

Troubleshooting

Related