Skip to main content

Virtuous CRM+ API Authentication

Scott Richards
  • Updated

Every CRM+ API request must include a valid Bearer token in the Authorization header. The API supports two token types: API Keys for server-to-server integrations, and OAuth tokens for integrations that act on behalf of a specific Virtuous user. This article provides guidance on the authentication process. 

To review the detailed API authentication, check out this document. 

Authentication Types

There are 2 authentication methods for the API:

  1. API Keys: Recommended for integrations and syncs. These Tokens are static and last for 15 years.
  2. OAuth Token authentication: Recommended for user-based interactions. These Tokens last 15 days and can be refreshed with a refresh Token that lasts 365 days.

For the majority of partner integrations, use an API Key. OAuth tokens are appropriate when your integration needs to perform actions as a specific Virtuous user — for example, an interactive admin tool where the user signs in with their own Virtuous credentials.

API Keys

To set up an API Key, navigate to All Settings and Connectivity. Select API Keys.

Screenshot 2026-06-11 at 13.35.01.png

Click Create a Key in the top right. Enter a descriptive name (typically the name of the integration you are building) and select the appropriate permission group. Click Save API Key.

Screenshot 2026-06-11 at 13.36.52.png

Once saved, copy the generated API Key to use in requests. Pass the key as a Bearer token in the Authorization header on every request:

Authorization: Bearer YOUR_API_TOKEN

OAuth Tokens

Obtain an OAuth Token

OAuth tokens are issued via a POST to https://api.virtuoussoftware.com/Token using the password grant type. URL-encode the email address and password before constructing the request body to handle special characters correctly.

Here is a quick example that shows how to request a token using cURL:

curl -X POST https://api.virtuoussoftware.com/Token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD"

Any future requests to the API will need to include the following header:

Authorization: Bearer access_token

Refresh Tokens

When the access token expires, use the refresh token to obtain a new one without requiring the user to re-authenticate. Refresh tokens are valid for 365 days.

curl -X POST https://api.virtuoussoftware.com/Token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN"

Store the new access_token and refresh_token from the response. Virtuous CRM_ may rotate the refresh token on each refresh, so always replace both.

Related articles