Articles in this section

See more

Authenticate Requests to the API Gateway

Avatar
Erin Gough
Updated

This article is intended for third party developers getting started developing an integration with Filevine. It outlines the steps for authenticating to the gateway. For more information on running further API requests, read the API documentation:

Filevine’s API gateway allows us to support the ongoing development of our application, and provides customers and the company with better monitoring of their API traffic. The gateway allows more precise tools to facilitate requests with more granular controls.

Prerequisite Steps

1. Request a Client ID and Secret from Filevine

The client ID and secret can be requested and viewed in the Account Manager. Click on your profile picture in the top right and click Manage My Account to open the Account Manager in a new tab.

In the Account Manager, click Access Tokens > Client Secrets. In this tab, you should see a popup option for requesting Higher API access. 

In this popup, click Next and fill out the form. If the request is approval, you will receive an email from Filevine with a secure link to the client ID and secret.

2. Create a Service Account User

Create a service account user that will represent the integration for testing. This user will perform the API actions, meaning that the user’s permission will be reflected in the API.

  1. In Filevine, navigate to Main Menu > Advanced > Service Accounts. 
  2. Click New and select the integration from the dropdown. 
  3. You can choose to grant all permissions to the service account, or elect to provide granular permissions manually later.
  4. Click Create.

3. Generate a Personal Access Token (PAT)

Before you make an authentication request to the gateway, you must generate a Personal Access Token (PAT) in Filevine.

Generate an access token in Filevine’s Account Manager. (You must be an Account Admin to generate access tokens.) 

To open the Account Manager, click your profile picture in the top right and click Manage My Account to open the Account Manager in a new tab. In the Account Manager, click Access Tokens > Personal Access Tokens. On this page, click + New to generate a PAT.

Read more about how to generate an access token.

Request a Bearer Token 

Make a POST request to the Filevine Identity endpoint below, using the information collected in the table and in step 1. You will receive a bearer token, its expiration time (listed in seconds), and the requested scopes.

Method POST
Endpoint/URI https://identity.filevine.com/connect/token 
Content-Type x-www-form-urlencoded
token enter the PAT generated in step 1A
grant_type personal_access_token
scope (enter exactly as listed here) fv.api.gateway.access tenant filevine.v2.api.* openid email fv.auth.tenant.read 
client_ID enter the client ID you’ve registered
client_secret enter the client secret you’ve registered

A Note on Scopes

The scopes for this request should be space-separated, not comma-delimited. They should be entered exactly as they appear in the preceding table. Read the following for more information about each of the scopes:

  • fv.api.gateway.access: generic scope for gateway access
  • tenant: access to FV Tenant (get tenant ID)
  • filevine.v2.api.*: access to Filevine API Methods
  • openid: get user information
  • email: get user email
  • fv.auth.tenant.read: scope for the  gateway to request the correct base URL path from FV Auth (tenant URL)

Request the User ID and Org ID

Perform a your first request to the API gateway to get your User ID and Org ID. You will use the bearer token (from step 2), the User ID, and the Org ID as headers in all further requests.

Method POST
Endpoint/URI https://api.filevineapp.com/fv-app/v2/utils/GetUserOrgsWithToken 
Auth Type Bearer Token
Token use the bearer token generated in step 2

In response, you  will receive the User ID and Org ID. 

Make Further Requests

Use Filevine’s API Documentation to make additional requests:

Use the bearer token and provide the User ID and Org ID as headers in all further requests.

Header Value
Authorization Bearer {token here}
x-fv-orgid {org id}
x-fv-userid {user id}

Comments

0 comments

Article is closed for comments.

Related articles