OIDC Integration Guide
- Joe Large
VDSapps offers APIs secured using OAuth 2.0 and OpenID Connect (OIDC), 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.
Overview
Registering your application in RapIDadmin will provide you with the information necessary to communicate with VDSapps' APIs.
Application Settings
During the application registration process, you will have the opportunity to configure the application’s properties.
Application Types
When you create a new application it is Private.
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.
Applications created using the Authorization Code grant type will receive both Development and Production client IDs and secrets.
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. For an example, the import scripts generated by the Data Management tool use the Device Code grant type.
Applications created using the Device Code grant type will receive a client ID only.
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).
Note: Applications within the same customer account use implied consent.
Development vs Production
The same tenant can be selected as both development and production.
Development keys are restricted to the selected development tenant, while production keys have broader access to other tenants that may exist within the same customer. For more information about how tenants relate to other tenants see Tenants.
Redirect URIs
Specify redirect locations
Examples
http://localhost:8080 (Development only)
Creating an Application
Sign in to RapIDadmin
Navigate to API > Applications
Click "Create"
Enter a Name, select the OAuth Grant Type, and select the required Scopes
Click "Save"
Securely store the provided Development and Production client IDs and secrets
client_id: Public app identifier
client_secret: Private, password-like information (never share)
Note: Secrets, where applicable, are displayed only once
Optionally, change the Development tenant
Enter a Development and/or Production redirect URI
Click "Save"
You can return to the application’s settings by selecting Actions > Edit.
Using Your Application
After receiving your keys you can begin using them immediately.
API Documentation
See EliteID Person API for field descriptions and usage
Swagger Documentation (Access requires a VDSapps account)
Endpoints
Authorization: https://www.vdsapps.com/connnect/authorize
How-to example 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.
Step 1. Start by creating an app in RapIDadmin with the following properties:
OAuth Grant Type: “Authorization Code”
Scopes: “EliteID API”
Redirect URI: https://oauth.pstmn.io/v1/browser-callback
Step 2. In Postman, click Import then paste the following the URL or content: https://www.vdsapps.com/EliteId/api/OpenApi
Step 3. After importing the APIs, the next step is to configure the Authorization.
Navigate to the Collection root folder
Select the Authorization tab
Set the Auth Type to “OAuth 2.0”
Add auth data to: “Request Headers”
Header Prefix: “Bearer”
Grant Type: “Authorization Code (With PKCE)”
Auth URL: https://www.vdsapps.com/rapidadmin/connect/authorize
Access Token URL: https://www.vdsapps.com/rapidadmin/connect/token
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.
Step 4. Apply the authorization to the API collection setting the child object’s Auth Type to “Inherit auth from parent”.
Step 5. Test by using POST to add a person then GET to view the person.
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
VDSapps API (Swagger) Documentation (Access requires a VDSapps account)
For technical details about the available API’s, please refer to the VDSapps API Documentation linked above or contact Vision Database support.