Skip to main content
Creating an application registers it. Configuring it is what makes it work. This page walks the four tabs of the app editor in the order you should fill them out, and explains what each field actually controls. Get these right before you build your authorize flow — most OAuth integration failures trace back to a configuration mismatch rather than to code.
Reach the editor from ‘Your apps’ in the developer dashboard, or directly at https://fluz.app/for-developers/overview/{appId}. Embedded widgets use the same tabs plus an additional Installation tab — see Configure App Widget.
Selecting an app to configure from Your apps

​
What’s on each tab

​
Overview tab

Two things live here, and they serve very different audiences.

​
Your credentials

The Client ID and Client Secret are on this tab. Every other page in this section that tells you to authenticate a request with Authorization: Basic base64(client_id:client_secret) means these values. The API Key and API Secret also live here — those are a separate pair with a separate job. See OAuth Applications for which credential does what.Copy them into your secret manager. Never into a browser bundle, a mobile binary, or source control.

​
Your public identity

The name, subtitle, description, avatar, and logomark are what your users see on the consent screen when they decide whether to hand your application access to their money. Treat these as product copy, not internal labels.
Review this tab even if you think you filled it out during creation. The three text fields are collected in the creation wizard, where it’s easy to type a placeholder and move on — and then ship it to a consent screen.

​
Permissions tab

This tab sets your scope ceiling: the maximum set of permissions your application may ever request from any user. It is not what any individual user has granted you. Scope selection on the Permissions tab

​
How selected scopes reach the user

Users don’t see raw enum values. Scopes you select are grouped under a readable top-level header, and it’s the header that’s presented for approval. A scope left unchecked is omitted entirely from what the user is asked to approve — and from what your app can ever request. How grouped scopes appear on the consent screen

​
Required scopes

Some scopes are mandatory for the app or widget type you’re configuring — without them the flow physically cannot run. These are gathered at the bottom of the tab, and the user cannot unselect them on the consent screen. You’ll see them there; you don’t choose them.

​
Choosing your scopes

Start from what the flow in front of you needs, not from what you might need someday. Full reference: Application Scopes.
Fewer scopes convert better. The consent screen is the highest-drop-off step in your integration, and its length is set by this tab. A narrower ceiling also limits the blast radius if a token leaks. Ask for what today’s flow needs; widen the ceiling when you build the next feature.

​
Scopes you can’t self-select

PCI_COMPLIANCE is administered by Fluz at the application level, granted to developers who have demonstrated PCI DSS compliance, and cannot be requested when generating a token. If you need to handle raw card data yourself, talk to your Fluz account manager. If you don’t want to, that’s what embedded widgets are for — they keep card capture inside Fluz’s PCI scope.

​
Changing scopes later

The permission model is an intersection of the app-level ceiling and each user’s grant, which has two practical consequences:
  • Adding a scope here does not retroactively grant it on tokens users already issued you. Existing users must re-authorize before the new scope becomes effective for them.
  • Removing a scope here narrows effective access immediately, for every user, regardless of what they previously approved.
Plan scope changes like schema migrations, not like config tweaks.

​
OAuth tab

Redirect URI configuration on the OAuth tab

​
Origin

The domain that will host the flow — example.com, app.example.com. For embedded widgets this is the page the widget renders on, and it must match or the widget won’t load.

​
Redirect URIs

Where our authorization server is permitted to send the user after they approve or decline.
  • Must be a public URL our servers can reach.
  • No query parameters on the registered URI. Use the state parameter to carry context instead.
  • Register as many as you need — one per environment, one per flow variant.
  • The URI you use at /authorize must be registered here, and the URI you send to /token/exchange must be byte-identical to the one you used at /authorize.
These are four different URIs as far as the authorization server is concerned:
Pick one canonical form, store it in a single constant, and use that same constant in both the authorize step and the exchange step. Hard-coding it twice is how mismatches happen.
Register your local callback explicitly — for example http://localhost:3035/oauth/finalize. It won’t work unless it’s on the list, and localhost URIs should not be left registered on a production app.

​
Webhook URLs

Public REST endpoints that receive events from Fluz — how you learn that a transfer completed, a user dismissed a modal, or a verification resolved, without polling.
  • Add as many URLs as you like.
  • Subscribe each URL to specific events, so you can route different event families to different services.
  • A URL with no events selected becomes a catch-all and receives everything. Convenient for development, noisy in production.
Your endpoint should acknowledge quickly and process asynchronously. Do the minimum work needed to accept the event, then hand it to a queue — a slow webhook handler turns into a delivery problem.

​
Verify before you build

Five minutes here saves an afternoon of debugging the authorize flow.
1

Credentials are out of the dashboard and into your secret store

Client ID, Client Secret, API Key, API Secret. Confirm nothing landed in a .env that’s tracked in git.
2

The consent screen reads well

Name, subtitle, description, avatar, logomark all populated and written for your users.
3

Every scope your code calls is checked on Permissions

Walk your intended API calls and confirm each one’s scope is enabled. A scope you request but haven’t enabled here is silently dropped, not rejected — so this mistake surfaces later as a confusing permission error.
4

Your redirect URI is registered in its exact canonical form

Including protocol, host casing, and trailing slash.
5

Build one authorize URL by hand and open it

Assemble /authorize with response_type=code, your client_id, your registered redirect_uri, and your scopes, then load it in a browser. If the consent screen renders with your branding and the scopes you expect, your configuration is correct. If it errors, the message names what didn’t match — and you’ve found it before writing any code.→ Client-facing OAuth grant flow

​
Staging and production are separate apps

Environments do not share configuration. A production application is registered separately, with its own Client ID, Client Secret, API Key, and API Secret, and its own redirect URIs and webhook endpoints pointed at live hosts. Nothing carries over from staging — including scope selections. Re-verify this entire page against your production app before launch. See Deploying to Production.

​
Troubleshooting

​
Next steps

Client-facing grant flow

Build the authorize URL and handle the callback.

Exchange an authorization code

Turn a code into an access token and refresh token.

Application scopes

The full scope reference.

Deploy to production

Re-register against live hosts and go live.