OAuth 2.0 Grants

The OAuth 2.0 code grant flow allows issuing access tokens on behalf of users. It means that your application can request authorization to access documents and other information in a user’s account and perform PDffiller operations on behalf of this user. In this case, the authentication process has several steps. To start the OAuth 2.0 authorization flow, you need to register your application or client in the PDFfiller API Settings. Upon registration, the application is assigned a Client ID and Client Secret, which will be used to send an authorization request to the user’s PDFfiller account and obtain an authorization grant. Generally, OAth 2.0 provides a number of methods, or grants, which allow the application to get the access tokens. PDFfiller API uses three types of authorization grants: authorization code grant, resource owner credentials grant, and refresh token grant.

Authorization Code Grant

The scheme of authorization code grant flow is as follows:

Step 1

The application redirects the user to: https://developers.pdffiller.com/api_access page with the following parameters in the query string:

  • client_id with the client identifier
  • redirect_uri with the client redirect URI

Step 2

The user authorizes the application to access the account, and the authorization code is returned to the above mentioned redirect URI with the following parameters in the query string:

  • code - authorization code
  • v - authorization token was successfully generated and can be used for v1 or v2.

Note: "v=fail" - V1 authorization token could not be generated. Please confirm your authorization credentials for v1 or contact our customer service department if you have any further questions.

Step 3

The application sends this authorization code to the PDFfiller authorization server and receives an access token: https://api.pdffiller.com/v1/oauth/token:

  • grant_type with the value of authorization_code
  • client_id with the client identifier
  • client_secret with the client secret
  • redirect_uri with the same redirect URI the user was redirected back to
  • code with the authorization code from the query string

Step 4

The authorization server will respond with a JSON object containing the following properties:

  • expires_in with an integer representing the TTL of the access token (i.e. when the token will expire)
  • access_token the access token itself
  • refresh_token a refresh token that can be used to acquire a new access token when the original expires

This grant type is used for confidential applications. The process of acquiring the access token can omit the specific steps from the authorization code grant scheme.

Resource Owner Credentials Grant

Resource owner credentials grant is recommended to use only with trusted first party applications. To obtain an access token, the application asks the user for their authorization credentials (user ID and password). When the credentials are received, the client sends the request to the authorization server:

  • grant_type with the value password
  • client_id with the client’s ID
  • client_secret with the client’s secret
  • username with the user’s username
  • password with the user’s password

The PDFfiller authorization server responds with a JSON object featuring the following:

  • token_type with the value Bearer
  • expires_in with an integer representing the TTL of the access token
  • access_token the access token itself
  • refresh_token a refresh token that can be used to acquire a new access token when the original expires

As we can see, this flow has fewer steps than the previous one. The client requests the access token from the PDFfiller authorization server and includes the user’s credentials into this request. Finally, the third type of the grant is a refresh token grant.

Refresh Token Grant

Eventually the acquired access token will expire. However, your application can receive credentials which allow getting a new access token without sending requests to the resource server. The refresh token is issued by the authorization server when the current access token expires. The refresh token is included in the process of issuing the access token. The flow of sending requests to the authorization server is as follows:

grant_type with the value refresh_token
refresh_token with the refresh token
client_id with the the client’s ID
client_secret with the client’s secret

The authorization server responds in the following manner:

  • token_type with the value Bearer
  • expires_in with an integer representing the TTL of the access token
  • access_token the access token itself
  • refresh_token a refresh token that can be used to acquire a new access token when the original expires

Before choosing what grant type to use, take into account these two main factors: the type of the application (first party or third party application) and the experience you’d like for your users.