Going Live

Prerequisite

Before going live, make sure you have read the page about Organizations. It's important to handle the case where your users' data resides in an organization vs. their personal account.

Security notice

You MUST create separate Request Finance accounts for your TEST/DEV and PRODUCTION OAuth applications.

User settings, including email, password, 2FA configuration, and OAuth applications, can be managed from either:

• Prod - app.request.finance

• Staging - baguette-app.request.finance

These settings are shared across environments. The same OAuth application gives you access to both environments.

Do not host all your OAuth applications under the same Request Finance account unless absolutely necessary. If you have to, you must protect your DEV and TEST client secrets with the same level of security as your PRODUCTION client secret. For example:

• Never store client secrets in plain text.

• Restrict secret access to authorized personnel only.

• Use a secure secret management solution.

Authentication

Replace API keys with the more secure OAuth authentication to go live with your application. Please follow these steps:

1. If you intend to act on your users' behalf, we advise setting up an account just for the integration, one that does not send or receive invoices, with a strong password that can be archived safely. (more info in 4.1)

2. You need to be authorized to access the Apps section, reach out to us with the integration account's email: here or via the Intercom chat.

3. Create an app in your Request Finance account on the "Developers" menu. Please read Security notice before creating any app.

   
4. Retrieve the access and refresh tokens from the provided Client Secret and Client ID:

   1. If you act on your users' behalf (ex: you are reading your users' invoices), follow the Authorization Code Flow. You can use any OAuth2 or OpenID-compatible library to do the heavy lifting. Auth0 also provides its own libraries here; choose any package corresponding to your language under "Regular Web App." For reference, we developed two implementation examples, one using NextJS and one using ExpressJS, available on this demo repository.

   2. If you act on your account's behalf (ex: you are sending invoices from your account to external users), you will need to follow the Client Credentials Flow. Reach out to us first to activate this flow. Note that you can only use one type of OAuth flow per app. You can find an example of how to implement it here. This flow only contains an access token (no refresh token), so you don't need to use the offline_access scope in the next step.

5. To configure the OAuth connection, you need to use the following parameters:

   URL: https://auth.request.finance
   Audience: accounts
   Scope: openid profile email offline_access

   Other scopes are also available, like user:read, see List organizations the user belongs to.

6. Save the access token and, in case of Authorization Code Flow, the refresh token too. Authenticate your API calls using the access token and reuse it until it expires (24 hours). After it expires, use the refresh token to ask for a new access token, or, in the case of Client Credential Flow, use your app secret to ask for a new access token. Here is an example of how to use the access token with NodeJS. Notice the mandatory X-Network header. Its values are either test or live.

fetch("https://api.request.finance/invoices", {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "X-Network": "live",
    },
  })

Optional: Transactional Emails

Transactional Emails require OAuth authentication as described above.

By default, we don't send transactional notifications for invoices created via API. If your users create invoices through your integration, you probably want issuers to be alerted of new invoices, and other transactional emails to be sent. In such case, please get in touch here or via the Intercom chat, and share your Client ID with the Request Finance team.

Troubleshooting

User does not have the right scope

If you are missing a scope for a given user (this can be verified by checking the issued access_token on https://jwt.io), you can add prompt=consent to the authorization URL to force updating the allowed scopes.

For instance, if you cannot get a refresh_token for a specific user, that user might miss the offline_access scope.

OIDC-Conformant Authentication

As of May 2026, we have adopted OIDC-conformant authentication. This introduces several structural changes to authentication requests, authentication responses, ID tokens, and access tokens. Notable changes include:

• response_type=token now only returns an access token. To receive an ID token, use response_type=id_token or response_type=token id_token.

• ID tokens are now signed asymmetrically using the RS256 algorithm.

• Authentication requests that do not include a nonce parameter will be rejected. For additional guidance, see Mitigate Replay Attacks When Using Implicit Flow.

• Refresh tokens are no longer returned when using the Implicit Flow for authentication.

Please review your integrations to ensure they are compatible with these updated OIDC requirements.