Virtuous API

https://docs.virtuoussoftware.com
Admin
The Virtuous API provides a RESTful interface for developers to programmatically manage...
Tokens:2,216
Snippets:21
Trust Score:8.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### OAuth Token Authentication with OTP

Source: https://docs.virtuoussoftware.com/

Explains how to obtain an OAuth token when Two-Factor Authentication (2FA) is enabled, requiring an OTP (One-Time Password).

```APIDOC
## OAuth Token Authentication with OTP

### Description
Obtain an OAuth token when Two-Factor Authentication (2FA) is enabled. After the initial request, you will receive a 202 response and need to provide the OTP sent to the user's phone.

### Method
POST

### Endpoint
`https://api.virtuoussoftware.com/Token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - `password`
- **username** (string) - Required - Your Virtuous account email address.
- **password** (string) - Required - Your Virtuous account password.
- **otp** (string) - Required - The One-Time Password received via SMS or authenticator app.

### Request Example
```bash
curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD&otp=YOUR_OTP" -X POST https://api.virtuoussoftware.com/Token
```

### Response
#### Success Response (200)
- **access_token** (string) - The OAuth token.
- **token_type** (string) - The type of token (e.g., Bearer).
- **expires_in** (integer) - The token's lifespan in seconds.
- **refresh_token** (string) - A token to refresh the access token.

#### Response Example
```json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 1296000,
  "refresh_token": "YOUR_REFRESH_TOKEN"
}
```
```

--------------------------------

### OAuth Token Authentication (Password Grant)

Source: https://docs.virtuoussoftware.com/

Shows how to obtain an OAuth token using a username and password. This method is recommended for user-based interactions.

```APIDOC
## OAuth Token Authentication (Password Grant)

### Description
Obtain an OAuth token using your email and password. This method is recommended for user-based interactions. Tokens last 15 days.

### Method
POST

### Endpoint
`https://api.virtuoussoftware.com/Token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - `password`
- **username** (string) - Required - Your Virtuous account email address.
- **password** (string) - Required - Your Virtuous account password.

### Request Example
```bash
curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD" -X POST https://api.virtuoussoftware.com/Token
```

### Response
#### Success Response (200)
- **access_token** (string) - The OAuth token.
- **token_type** (string) - The type of token (e.g., Bearer).
- **expires_in** (integer) - The token's lifespan in seconds.
- **refresh_token** (string) - A token to refresh the access token.

#### Response Example
```json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 1296000,
  "refresh_token": "YOUR_REFRESH_TOKEN"
}
```
```

--------------------------------

### API Key Authentication

Source: https://docs.virtuoussoftware.com/

Demonstrates how to authenticate API requests using an API Key via the Authorization header. API Keys are recommended for integrations and syncs and have a long lifespan.

```APIDOC
## API Key Authentication

### Description
Use API Keys for integrations and syncs. Tokens are static and last 15 years.

### Method
Not applicable (Header-based authentication)

### Endpoint
Not applicable

### Parameters
#### Headers
- **Authorization** (string) - Required - `Authorization: {{vault:bearer-token}}`

### Request Example
```bash
curl -H "Authorization: {{vault:bearer-token}}" https://api.virtuoussoftware.com/some/endpoint
```

### Response
#### Success Response (200)
- **Data** (object) - The response from the API endpoint.

#### Response Example
```json
{
  "data": {}
}
```
```

--------------------------------

### Configure Virtuous Forms Settings

Source: https://docs.virtuoussoftware.com/

Load default values and define a success event handler for Virtuous Forms. The onSuccess function can be used for tracking events with analytics platforms or displaying custom messages.

```javascript
let VirtuousForms = VirtuousForms || {};
VirtuousForms.settings = {
     firstName: 'DEFAULT_VALUE',
     lastName: 'DEFAULT_VALUE',
     email: 'DEFAULT_VALUE',
     onSuccess: function(response) {
          //track event here....
     }
};
```

--------------------------------

### Request Token with OTP for Two-Factor Authentication

Source: https://docs.virtuoussoftware.com/

When a user has Two-Factor Authentication enabled, you will receive a 202 response. After the user provides the OTP, use this cURL command including the 'otp' header to complete the token request.

```cURL
curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD&otp=YOUR_OTP" -X POST `https://api.virtuoussoftware.com/Token`
```

--------------------------------

### Request Token using OAuth Password Grant

Source: https://docs.virtuoussoftware.com/

Use this cURL command to request an OAuth token by providing your email and password. Ensure that your email and password are URL encoded if they contain special characters.

```cURL
curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD" -X POST `https://api.virtuoussoftware.com/Token`
```

--------------------------------

### Refresh OAuth Token using Refresh Token

Source: https://docs.virtuoussoftware.com/

Use this cURL command to obtain a new access token by providing your stored refresh token. This is useful when your current access token has expired.

```cURL
curl -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN" -X POST `https://api.virtuoussoftware.com/Token`
```

--------------------------------

### OAuth Token Refresh

Source: https://docs.virtuoussoftware.com/

Demonstrates how to refresh an expired OAuth token using a refresh token. This is part of the OAuth 2.0 flow for maintaining user sessions.

```APIDOC
## OAuth Token Refresh

### Description
Refresh an expired OAuth token using a previously obtained refresh token. This allows for continuous access without requiring the user to re-authenticate frequently.

### Method
POST

### Endpoint
`https://api.virtuoussoftware.com/Token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - `refresh_token`
- **refresh_token** (string) - Required - The refresh token obtained during the initial OAuth token request.

### Request Example
```bash
curl -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN" -X POST https://api.virtuoussoftware.com/Token
```

### Response
#### Success Response (200)
- **access_token** (string) - The new OAuth token.
- **token_type** (string) - The type of token (e.g., Bearer).
- **expires_in** (integer) - The new token's lifespan in seconds.
- **refresh_token** (string) - A new refresh token (may be the same or different).

#### Response Example
```json
{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 1296000,
  "refresh_token": "NEW_REFRESH_TOKEN"
}
```
```
Tokens:
Raw