> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a partner app with OAuth and manage installed apps

> Register an OAuth app, take customers through the Flowella consent screen, exchange codes for tokens, and review or revoke apps installed in your organisation.

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](https://knowledge.flowella.io/settings/api-keys.md) 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.

```mermaid theme={null}
sequenceDiagram
    participant Admin as Customer admin
    participant App as Your app
    participant Flowella
    App->>Admin: Redirect to the Flowella authorise URL
    Admin->>Flowella: Open the authorise URL
    Flowella->>Admin: Show the consent screen
    Admin->>Flowella: Select Allow access
    Flowella->>App: Redirect back with a code
    App->>Flowella: Exchange the code and verifier
    Flowella->>App: Access and refresh tokens
    App->>Flowella: Call the API with the access token
```

## 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

**1. Open Developer apps**

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

**2. Start a new app**

Select **Create app**. The **Create developer app** dialog opens.

**3. Name the app**

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

**4. 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.

**5. 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](https://knowledge.flowella.io/api-reference/introduction.md#scopes).

**6. 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**.

> [!WARNING]
>
> 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:

```text theme={null}
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

1. If the person is not signed in, Flowella asks them to sign in first.
2. The person must be an **Owner** or **Admin** of the organisation. Anyone else sees the error `Owner or admin role required to authorize apps`.
3. 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.**
4. 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.

```bash theme={null}
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:

```json theme={null}
{
  "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:

```http theme={null}
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](https://knowledge.flowella.io/api-reference/introduction.md).

> [!NOTE]
>
> `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:

1. Go to **Settings**, then select **Installed apps** in the **Developer** group.
2. Select **Revoke** on the app's row.
3. 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.

> [!NOTE]
>
> 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](https://knowledge.flowella.io/settings/team.md#change-someones-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.

## Related

> **[API introduction](https://knowledge.flowella.io/api-reference/introduction.md)**
>
> Authentication, scopes, rate limits and errors.

> **[Developer hub](https://knowledge.flowella.io/settings/developer-hub.md)**
>
> Recent API requests, quickstarts and the API sandbox.

> **[API keys](https://knowledge.flowella.io/settings/api-keys.md)**
>
> Simpler access for your own scripts and integrations.

> **[Webhooks reference](https://knowledge.flowella.io/api-reference/webhooks.md)**
>
> React to events in the organisations that install your app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.