VDSapps offers APIs secured using OAuth 2.0 and OpenID Connect, allowing customers and third-party applications to access user data without exposing login credentials. This guide covers the integration process, including creating your first app and connecting to the APIs.

Application Registration

To integrate with VDSapps APIs, register your application in RapIDAdmin. During the registration process, you will have the opportunity to configure the application properties.

Application Types

Private Application

• Provides access to a single customer’s data

• Can be tied to both development and production tenants

• Can use either Authorization Code or Device Code flow

Publishable Application

• Available for developer accounts (3rd party integrators)

• Works with other customer accounts

• Must be configured as publishable during creation (cannot be changed later)

• Can only use the Authorization Code flow

OAuth Grant Types

Authorization Code

The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token.

After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token.

Device Code

The Device Code grant type is used by browserless or input-constrained devices in the device flow to exchange a previously obtained device code for an access token.

Scopes and Consent

The application scope defines which resources your application will need access to. The scopes your application requests will be presented to the user when they consent to giving your application access to their data. Using the principal of least privilege, only request the scopes your application will be using. You can modify this property as your needs change.

Available scopes

• rapidadmin.api

• eliteid.api

• perfectpass.api

Once a user grants consent, the permission appears in the Connections section. This listing specifies whether the application is internal (customer-created) or external (published).

Redirect URIs

Specify redirect locations

• Examples: https://oauth.pstmn.io/v1/browser-callback, http://localhost:8080 (Development only)

Endpoints

• Authorization: https://www.vdsapps.com/connnect/authorize

• Token: https://www.vdsapps.com/connect/token

Process

1. Obtain user permission through the authorization flow

2. User logs in (if not already)

3. User grants consent (first-time connections)

4. Redirect to specified URI

5. Complete token exchange

Creating Your First Application

1. Sign in to RapIDadmin

2. Navigate to API > Applications

3. Click "Create"

4. Enter a Name, select the OAuth Grant Type, and select the required Scopes

5. Click "Save"

6. Securely store the provided Development and Production client IDs and secrets

   • Note: Secrets, where applicable, are displayed only once

   • client_id: Public app identifier

   • client_secret: Private, password-like information (never share)

7. Optionally, change the Development tenant

8. Enter a Development and/or Production redirect URI

9. Click "Save"

Using Your Application

After receiving your key(s) you can begin using them immediately.

Development Using Postman

In this example we will create an application with the Authorization Code grant type. Then, we’ll use Postman to access the EliteID APIs.

Start by creating an app in RapIDadmin with the following properties:

1. OAuth Grant Type: “Authorization Code”

2. Scopes: “EliteID API”

3. Redirect URI: https://oauth.pstmn.io/v1/browser-callback

In Postman, click Import then enter the URL or paste the contents: https://www.vdsapps.com/EliteId/api/OpenApi

After importing the APIs, the next step is to configure the Authorization.

1. Navigate to the Collection root folder

2. Select the Authorization tab

3. Set the Auth Type to “OAuth 2.0”

4. Add auth data to: “Request Headers”

5. Header Prefix: “Bearer”

6. Grant Type: “Authorization Code (With PKCE)”

7. Auth URL: https://www.vdsapps.com/rapidadmin/connect/authorize

8. Access Token URL: https://www.vdsapps.com/rapidadmin/connect/token

9. Client ID: <Enter Client ID>

10.  Client Secret: <Enter the Client Secret>

11.  Code Challenge Method: “SHA-256”

12.  Code Verifier: <blank>

13.  Scope: “eliteid.api offline_access”

14.  State: <blank>

15.  Client Authentication: “Send as Basic Auth header”

16.  Click “Get New Access Token”

17.  Sign in using the account that created the app, if not already signed in.

Upon successful authorization a token is returned that can be saved for future use.

Apply the authorization to the API collection by clicking on each sub-folder and setting the Auth Type to “Inherit auth from parent”.

Application Publication

To make your app available to other customers, contact Vision Database support.

Security Considerations

• Keep client secrets secure and never share them publicly

• Use appropriate application types based on secret storage capabilities

• Follow the principle of least privilege when selecting scopes

Resources

• OAuth Community Site

• OAuth.com - OAuth 2.0 Simplified

• RFC 6749: The OAuth 2.0 Authorization Framework

• OpenID Connect: How it Works (OpenID Foundation)

• VDSapps API Documentation (Requires Authentication)

For more information on VDSapps API integration, please refer to the API documentation or contact Vision Database support.