Create an Access token and learn how to authenticate on the Peoplevine REST APIs.
Authenticate with the Peoplevine APIs
Peoplevine uses JWT (JSON Web Tokens) that are short-lived to authenticate requests on their APIs. Short-lived tokens last for 30 minutes before they need to be refreshed using the Refresh token. There are 3 different token types that can be created:
User: This token is used to authenticate to the control panel of the Peoplevine system. It is generally associated with multiple companies. It is short-lived token that is created via authentication to the Peoplevine api/token endpoint with the username, password, and grant_typeparameters, with grant type set to password. The company_id parameter is not used. This token has access to the api/company endpoint, which returns a list of companies associated with the user. Once a User token has been granted, it can be used to obtain a User Company token. Navigate to Generate a User Access token for more information.
User Company: This is the most commonly used token. A User token must be created prior to obtaining a User Company token. It is a short-lived token that is created by authentication on the api/token endpoint using the refresh_token and access_token of the User, company_id, and grant_typeparameters, with grant type set to access_token. To obtain this token, first generate a User Access token, and then navigate to Generate a User Company Access token.
Customer: A short-lived token used to authenticate your customer to your app that is created by authenticating on the api/token endpoint with the username, password, company_id, and grant_typeparameters, with grant type set to customer_password. You can go to Generate a Customer Access token for more information on how to create this token type.
More information about tokens can be found in the Peoplevine Tokens page.
Parameters
The following parameters are used to authenticate with the Peoplevine APIs.
username: The email address used to sign up for a Peoplevine account.
password: The password for the Peoplevine account.
company_id: The numeric ID associated with the Company in the Peoplevine account. This can be located in the company profile on the Control Panel.
grant_type: The authentication method used to authenticate with the API. This can be set toaccess_token, customer_password, or password, depending on the desired access token.
remember_me: When set to "true", the Refresh token can be used for 7 days, but when set to "false", it can only be used for 24 hours.
Generate a User Access token
API users must obtain a User Company token after receiving a User Access token to exercise the API
To authenticate on the API, you need to make a token request on the api/token/ endpoint with the grant_type set to "password" using the following command, replacing the sample data (indicated by <>) with your information.
This error is caused by providing invalid authentication credentials or using an expired/invalid access or refresh token.
The token used does not have the proper permission to view the requested resource. Items with their visibility set to members only will return a 403 response if the customer does not have an active membership. This error should be reported back to the user.
{"error":"invalid_request","title":"Invalid Request","error_description":"Invalid username or password combination","error_details": {"attempts_remaining":4 },"request_id":"req__uIRVeRqqy9PTi7O35dDY1soy"}
The token used has reached the request rate limit. View Rate Limit details for information on the rate limit caps.
In the unlikely event that a 500 error response is returned, report this to the Peoplevine Support team for assistance.
This token can now be used to obtain a User Company Access token.
Generate a User Company Access Token
After you have a User Access token, you can use the information in the response to request a User Company Access token. Paste the refresh_token and the access_token from the response, and modify grant_type to access_token. Then paste your company ID from your company profile in the Peoplevine control panel into the company_id parameter.
This error is caused by providing invalid authentication credentials or using an expired/invalid access or refresh token.
The token used does not have the proper permission to view the requested resource. Items with their visibility set to members only will return a 403 response if the customer does not have an active membership. This error should be reported back to the user.
{"error":"invalid_request","title":"Invalid Request","error_description":"Invalid username or password combination","error_details": {"attempts_remaining":4 },"request_id":"req__uIRVeRqqy9PTi7O35dDY1soy"}
The token used has reached the request rate limit. View Rate Limit details for information on the rate limit caps.
In the unlikely event that a 500 error response is returned, report this to the Peoplevine Support team for assistance.
Now you are ready to start making requests to the Peoplevine APIs.
Generate a Customer Access token
A Customer Access token is used to authenticate your customers to your app in order for them to access your Peoplevine member portal. This token is tied to visibility privileges, so it hides any resources the customer does not have access to.
This error is caused by providing invalid authentication credentials or using an expired/invalid access or refresh token.
The token used does not have the proper permission to view the requested resource. Items with their visibility set to members only will return a 403 response if the customer does not have an active membership. This error should be reported back to the user.
{"error":"invalid_request","title":"Invalid Request","error_description":"Invalid username or password combination","error_details": {"attempts_remaining":4 },"request_id":"req__uIRVeRqqy9PTi7O35dDY1soy"}
The token used has reached the request rate limit. View Rate Limit details for information on the rate limit caps.
In the unlikely event that a 500 error response is returned, report this to the Peoplevine Support team for assistance.
Add User Company Access token requests to your code
You can both request and refresh a token programmatically in your app code to reduce the need for manual interaction with the APIs. Click the tab below matching your app language for example code snippets. Make sure to replace the following text with your company's information to make the code work as expected.
username
password
company_id
// Define the base URL for the API
const baseUrl = 'https://api.peoplevine.com/api/token';
// Define the interface for the user authentication response
interface UserAuthResponse {
refresh_token: string;
access_token: string;
}
async function authenticate(): Promise<void> {
try {
// Define the JSON payload for user authentication
const userAuthPayload = {
username: 'example@example.com',
password: '****',
grant_type: 'password',
remember_me: true,
};
// Send the user authentication request
const userAuthResponse = await fetch(baseUrl, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(userAuthPayload),
});
if (!userAuthResponse.ok) {
throw new Error('User authentication request failed');
}
const { refresh_token, access_token } = await userAuthResponse.json() as UserAuthResponse;
// Define the JSON payload for company authentication
const companyAuthPayload = {
refresh_token,
access_token,
grant_type: 'access_token',
company_id: 1234567,
};
// Send the company authentication request
const companyAuthResponse = await fetch(baseUrl, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(companyAuthPayload),
});
if (!companyAuthResponse.ok) {
throw new Error('Company authentication request failed');
}
const companyAuthResult = await companyAuthResponse.json();
// Handle the response from the company authentication request
console.log(companyAuthResult);
} catch (error) {
// Handle any errors that occurred during the requests
console.error('An error occurred:', error);
}
}
// Call the authenticate function
authenticate();
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
await Authenticate();
}
static async Task Authenticate()
{
try
{
// Define the base URL for the API
string baseUrl = "https://api.peoplevine.com/api/token";
// Create an HttpClient instance
using var client = new HttpClient();
// Define the JSON payload for user authentication
var userAuthPayload = new
{
username = "example@example.com",
password = "****",
grant_type = "password",
remember_me = true
};
// Serialize the payload to JSON
string userAuthJson = JsonSerializer.Serialize(userAuthPayload);
// Send the user authentication request
HttpResponseMessage userAuthResponse = await client.PostAsync(baseUrl, new StringContent(userAuthJson, Encoding.UTF8, "application/json"));
userAuthResponse.EnsureSuccessStatusCode();
// Deserialize the response content to a UserAuthResponse object
string userAuthContent = await userAuthResponse.Content.ReadAsStringAsync();
var userAuthResult = JsonSerializer.Deserialize<UserAuthResponse>(userAuthContent);
// Define the JSON payload for company authentication
var companyAuthPayload = new
{
refresh_token = userAuthResult.RefreshToken,
access_token = userAuthResult.AccessToken,
grant_type = "access_token",
company_id = 1234567
};
// Serialize the payload to JSON
string companyAuthJson = JsonSerializer.Serialize(companyAuthPayload);
// Send the company authentication request
HttpResponseMessage companyAuthResponse = await client.PostAsync(baseUrl, new StringContent(companyAuthJson, Encoding.UTF8, "application/json"));
companyAuthResponse.EnsureSuccessStatusCode();
// Handle the response from the company authentication request
string companyAuthContent = await companyAuthResponse.Content.ReadAsStringAsync();
Console.WriteLine(companyAuthContent);
}
catch (Exception ex)
{
// Handle any errors that occurred during the requests
Console.WriteLine($"An error occurred: {ex.Message}");
}
}
}
// Define the UserAuthResponse class for deserialization
class UserAuthResponse
{
public string RefreshToken { get; set; }
public string AccessToken { get; set; }
}
This will automatically create the User Access token, then create the User Company Access token. It will also refresh a token automatically when the Access token expires.