Headed 3rd Party App Integrations

This guide is intended for third party developers who would like to integrate their applications with Filevine API using OAuth 2.0 / OpenID Connect (OIDC). Once set up, your users log in with their Filevine credentials and your app receives tokens to call the Filevine API on their behalf.

This process is an alternative to the PAT process for integrations.

• High-Level Authentication Flow
• Step-by-Step
• Working Code Examples

High-Level Authentication Flow

Filevine uses a standards-based OAuth 2.0 + OpenID Connect identity platform. For a server-side application (e.g. a reporting dashboard with a backend), the correct flow is Authorization Code with a Client Secret (confidential client). The flow works like this:

1. The user clicks Login with Filevine in your app.
2. Your app redirects the user to Filevine's hosted login page (the authorization endpoint).
3. After the user authenticates, Filevine redirects back to your redirect_uri with an authorization code.
4. Your server exchanges the code (plus your client_secret) for an access token and refresh token.
5. Include the access token as a Bearer token on all Filevine API requests.
6. Use the refresh token to get new access tokens without requiring the user to log in again.

Step-by-Step

1. Request a Client from Filevine

Before you can integrate, Filevine must provision an OAuth client for your application. Contact your Filevine partner representative and provide:

• Application name (e.g. "Vineskills Reporting Platform")
• Redirect URI – the callback URL in your app that Filevine sends users back to after login (e.g. https://yourapp.com/auth/callback)
• Post-logout redirect URI – where to send users after they log out
• Required scopes (see Step 3 below)
• Target environment(s): Production US, Production Canada

Filevine will return a client_id and client_secret. 

Permission Required

Keep the client_secret secure. Never expose it in client-side or browser code.

2. Configure Your Application

Once you have your credentials, configure your OIDC library with these values:

Authority (OIDC issuer URL)	Set to the appropriate URL for your target environment:  Production (US): https://identity.filevine.com Production (Canada): https://identity.filevine.ca Appending /.well-known/openid-configuration to any of these gives you the full OIDC discovery document (all endpoint URLs, supported scopes, etc.).
ClientId	provided by Filevine
Client Secret	provided by Filevine  Heads Up! Store the client secret in an environment variables / secrets manager—never in the source code.
RedirectUri	This must exactly match what was registered with Filevine in step 1.
Post Logout Redirect Uri	This must exactly match what was registered with Filevine in step 1.
Scopes	Scopes should be listed in a space-separated list. Request only the scopes your app actually needs: openid: required for OIDC profile: user's name and basic profile info email: user's email address offline_access: enables refresh tokens so your app can call the API without requiring the user to re-login fv.api.gateway.access: grants access to call the Filevine API gateway Your Filevine contact can advise on additional API-specific scopes based on the resources your integration needs to access.

3. Call the Filevine API

Once authenticated, include the access token, returned in the response, in all API requests as a Bearer token:

GET <https://api.filevine.io/v2/projects>

Authorization: Bearer <access_token>

Your Filevine contact will provide the specific API gateway base URL and the endpoints relevant to your integration.

Working Code Examples

Filevine provides three working reference implementations on GitHub. Each demonstrates the full Authorization Code flow including token acquisition, session management, token refresh, and API calls:

• Node.js (Express + openid-client + Passport): https://github.com/Filevine/filevine-api-examples/tree/main/FV.API.SamplePartnerAppJs
• Python (Django + Authlib): https://github.com/Filevine/filevine-api-examples/tree/main/FV.API.SamplePartnerAppPy
• C# (.NET): https://github.com/Filevine/filevine-api-examples/tree/main/FV.API.Examples.SamplePartnerApp

Each sample runs on localhost:7059. The Node.js sample uses a config.json (with Authority, ClientId, ClientSecret, RedirectUri, Scopes, and API gateway URL). The Python sample uses a .env file with the same values. These config files show exactly what needs to be filled in once Filevine provisions your client.