Authentication

VeriPlus API uses API keys for authentication. All requests must include a valid API key in the Authorization header.

API Keys

Key Types

Creating API Keys

1. Log in to VeriPlus Dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Choose environment (Live or Test)
5. Add description (e.g., "Production Server", "Staging Environment")
6. Click Generate

Key Format

vp_live_1234567890abcdefghijklmnopqrstuvwxyz
vp_test_abcdefghijklmnopqrstuvwxyz1234567890

• Length: 48 characters (including prefix)
• Alphanumeric characters only
• Case-sensitive

Making Authenticated Requests

Basic Authentication

Include the API key in the Authorization header with Bearer scheme:

const apiKey = process.env.VERIPLUS_API_KEY;
 
const response = await fetch('https://api.veriplus.co.uk/api/v3/applicants', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});
 
const data = await response.json();

Authentication Errors

Example Error Response:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "details": {
      "suggestion": "Generate a new API key from the dashboard"
    }
  }
}

API Key Management

Rotating Keys

Best practice: Rotate API keys every 90 days.

Process:

1. Generate new API key in dashboard
2. Update environment variables in your application
3. Deploy updated configuration
4. Verify new key works
5. Revoke old key

Revoking Keys

Revoke a compromised key immediately:

1. Dashboard → Settings → API Keys
2. Find the compromised key
3. Click Revoke
4. Generate a new key

Effect: All requests with revoked key return 401 EXPIRED_API_KEY

Key Scopes (Coming Soon)

Future feature: Restrict API keys to specific resources or actions.

Example planned scopes:

• applicants:read - Read applicant data
• applicants:write - Create/update applicants
• verifications:create - Start verifications
• aml:search - Perform AML searches

Security Best Practices

1. Store Keys Securely

✅ DO:

• Store in environment variables
• Use secrets management (AWS Secrets Manager, HashiCorp Vault)
• Encrypt at rest
• Restrict access to authorised personnel

❌ DON'T:

• Hardcode in source code
• Commit to Git repositories
• Share via email or chat
• Log in application logs

2. Use Environment-Specific Keys

// ✅ Good
const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.VERIPLUS_LIVE_KEY
  : process.env.VERIPLUS_TEST_KEY;
 
// ❌ Bad - hardcoded
const apiKey = 'vp_live_abc123...';

3. Implement Key Rotation

// Automated rotation example (Node.js)
const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();
 
async function getApiKey() {
  const secret = await secretsManager.getSecretValue({
    SecretId: 'veriplus/api-key'
  }).promise();
 
  return JSON.parse(secret.SecretString).apiKey;
}

4. Monitor Key Usage

Check for unusual activity:

• Requests from unexpected IP addresses
• Spike in API calls
• Failed authentication attempts

Dashboard → Settings → API Keys → View Activity

5. Use HTTPS Only

All API requests MUST use HTTPS. HTTP requests will be rejected.

✅ https://api.veriplus.co.uk/api/v3/...
❌ http://api.veriplus.co.uk/api/v3/...

6. Implement Rate Limiting

Client-side rate limiting prevents hitting API limits:

const pLimit = require('p-limit');
const limit = pLimit(10); // Max 10 concurrent requests
 
const promises = applicants.map(applicant =>
  limit(() => createVerification(applicant))
);
 
await Promise.all(promises);

Organization Context

API keys are scoped to your organisation. All resources created via the API belong to the key's organisation.

Organization ID

Automatically extracted from API key. No need to provide organizationId in requests.

// ❌ Don't do this
const response = await fetch('/api/v3/applicants', {
  body: JSON.stringify({
    organizationId: 'org_abc123', // Not needed
    firstName: 'John'
  })
});
 
// ✅ Do this
const response = await fetch('/api/v3/applicants', {
  body: JSON.stringify({
    firstName: 'John' // organizationId inferred from API key
  })
});

IP Whitelisting (Enterprise)

Enterprise plans can restrict API access to specific IP addresses.

Setup:

1. Dashboard → Settings → Security
2. Enable IP Whitelisting
3. Add allowed IP addresses (CIDR notation supported)

192.168.1.100/32
10.0.0.0/16
203.0.113.0/24

Effect: Requests from non-whitelisted IPs return 403 FORBIDDEN

Webhook Authentication

Verify webhook requests from VeriPlus using signature validation:

const crypto = require('crypto');
 
function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
 
// Express.js middleware
app.post('/webhooks/veriplus', (req, res) => {
  const signature = req.headers['x-veriplus-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );
 
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  // Process webhook...
});

See Webhooks Documentation for complete reference.

Testing Authentication

Test your API key:

const response = await fetch('https://api.veriplus.co.uk/api/v3/auth/verify', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});
 
const data = await response.json();
console.log(data);
// {
//   "success": true,
//   "data": {
//     "valid": true,
//     "organization": {
//       "id": "org_abc123",
//       "name": "Acme Corp",
//       "plan": "PROFESSIONAL"
//     },
//     "scopes": ["*"]
//   }
// }

Common Issues

Issue: 401 Unauthorised

Causes:

• Missing Authorization header
• Incorrect Bearer scheme (Bearer not Basic)
• API key typo or truncated
• API key revoked

Solution:

// Check your header format
headers: {
  'Authorization': `Bearer ${apiKey}`,  // Correct
  // Not: 'Authorization': apiKey       // Wrong
  // Not: 'Authorization': `Basic ${apiKey}` // Wrong
}

Issue: 403 Forbidden

Causes:

• Insufficient plan permissions
• IP not whitelisted (Enterprise)
• Feature not included in plan

Solution: Upgrade plan or contact support to enable feature.

Issue: Rate limit exceeded

Cause: Too many requests in short time

Solution: Implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
 
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
 
    return response;
  }
 
  throw new Error('Max retries exceeded');
}

Next Steps