Authentication

The vPlan API allows for two types of authentication; OAuth 2 and API Key.

API Keys are great for rapid prototyping and easy access.
For increased security, integrations should strive to use OAuth 2, especially if the integration is designed for multiple customers.

WARNING

An API Key is static and gives unsupervised access to an account, to improve security we recommend to replace API Keys at least every 6 months.

Customers will receive reminders advising to replace their API Key.

As stated OAuth 2 does not have this security risk.

In this document the headers are included in the examples. The credentials that need to be filled in this header are replaced with a placeholder {token}.

Api-Key

The Api-Key is to be used in combination with Api-Env.

The two headers combined can be used as authentication.

Creating an Api-Key

Perform the following steps:

Log into vPlan;

In the side-menu click on Settings;

In the side-menu click on API Keys;

Click on the "ADD KEY" button.

Header parameter name: X-Api-Key, given key from vPlan. Will change if new Api-key is generated
Header parameter name: X-Api-Env, identifier for current environment

OAuth 2

Resources on OAuth:

OAuth 2 specification

Simplified explanation

Roles

OAuth 2 Role	Application
Client	Application using this API
Resource Server	The vPlan API service
Authorization Server	Most Wanted OAuth 2 Authorization Server
Resource Owner	The user of the vPlan environment

Creating an app

To create an app which users can connect to their vPlan environment, go to https://developer.vplan.com/.
Registration of the app provides a client id and client secret. This information is specific to the app. The client secret should never be shared publicly.

Registration requires a redirect URI, this should be the base URI to which all callbacks will be performed, this URI must be publicly accessible.

Security Scheme Type: OAuth2
Flow type: authorizationCode
Authorization URL: https://developer.mostwanted.io/api/v1/oauth/authorize
Token URL: https://developer.mostwanted.io/api/v1/oauth/token

Authentication

Api-Key#

Creating an Api-Key#

OAuth 2#

Roles#

Creating an app#

Api-Key

Creating an Api-Key

OAuth 2

Roles

Creating an app