Authentication Guide

Authentication

All API requests to VEC.digital require authentication using an API token. This guide explains how to obtain and use an API token for your API requests.

Obtaining an API Token

Follow these steps to create an API token:

1. Sign in to your institution account at vec.digital/login
2. Navigate to your account settings
3. Go to the “API Tokens” section
4. Click “Create New Token”
5. Give your token a descriptive name and select the required permissions
6. Copy and securely store the token - it will only be shown once

Using the API Token

The VEC.digital API uses bearer authentication. Include your API token in the Authorization header of each request:

GET /business/certificate-templates HTTP/1.1
Host: api.vec.digital
Authorization: Bearer YOUR_API_TOKEN

Example with cURL

curl -X GET \
  'https://api.vec.digital/business/certificate-templates' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Example with JavaScript (Fetch API)

const fetchTemplates = async () => {
  const response = await fetch('https://api.vec.digital/business/certificate-templates', {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'Authorization': `Bearer YOUR_API_TOKEN`
    }
  });

  const data = await response.json();
  return data;
};

Example with PHP

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.vec.digital/business/certificate-templates');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'Authorization: Bearer YOUR_API_TOKEN'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

curl_close($ch);
?>

Token Security

API tokens provide full access to your account via the API. To keep your account secure:

• Store tokens securely
• Never share tokens publicly
• Use different tokens for different applications
• Assign only necessary permissions to each token
• Regularly audit and rotate your tokens

Error Responses

If authentication fails, you will receive one of the following responses:

• 401 Unauthorized: No API token provided, or the token is invalid
• 403 Forbidden: The token is valid but doesn’t have permission for the requested action

Example error response:

{
  "message": "Unauthorized - Invalid API token"
}

Token Permissions

When creating an API token, you can select specific permissions. Available permissions include:

• certificate-templates:list - View certificate templates
• certificate-templates:view - View individual certificate templates
• batches:list - View certificate batches
• batches:create - Create certificate batches
• batches:view - View individual certificate batches
• batches:status - Check certificate batch status
• certificates:list - View certificates
• certificates:view - View individual certificates
• certificates:download - Download certificate PDFs
• read:users - View institution users

Ensure your token has all the necessary permissions for your application needs.