Authentication

User sesssions must be authenticated. The Verdocs Platform API provides four standard OAuth2 workflows/grants to support this:

1. ROPC. Traditional login with username and password. This is the simplest and most common workflow, but will be retired in favor of PKCE in 2025.
2. PKCE. Modern, more secure replacement for ROPC that helps prevent CSRF and click-jacking attacks. Will be available by Jan. 2025.
3. Client Credentials. For server applications, replaces username/password authentication with client ID/secret credentials.
4. Refresh Token. For an active session about to expire, exchanges a (valid) refresh token for a new set of session tokens with a later expiration.

Standard User Authentication

To authenticate as a standard user, present the user with a login form to enter their username and password, then use code such as shown below. NOTE: You may also embed the VerdocsAuth component in your Web application, and this is strongly recomended.

import {VerdocsEndpoint, authenticate} from '@verdocs/js-sdk';

const endpoint = VerdocsEndpoint.getDefault();
const authResult = await authenticate(endpoint, { 
  grant_type: 'password', 
  username: USER, 
  password: PASS 
});
endpoint.setToken(authResult.access_token);

Server Application Authentication

Server applications should never "know" usernames and passwords. Instead, create an API key in your account, and securely store the Client ID and Secret in an appropriate location such as Vault, Secrets Manager, SSM, etc. Then use code such as the following to authenticate:

import {VerdocsEndpoint, authenticate} from '@verdocs/js-sdk';

const endpoint = VerdocsEndpoint.getDefault();
const authResult = await authenticate(endpoint, { 
  grant_type: 'client_credentials', 
  client_id: ID, 
  client_secret: SECRET 
});
endpoint.setToken(authResult.access_token);

NOTE: Client-credentials tokens have short expiration times, and should be rotated/refreshed frequently.

That's it! You can now proceed to call the Verdocs Platform API.