Authentication

Learn how to authenticate your API requests using API keys

Overview

The Vemetric API uses API keys for authentication. All API requests must include a valid API key in the Authorization header using the Bearer authentication scheme.

Creating an API Key

1. Navigate to Project Settings

   Log in to your Vemetric dashboard and select the project you want to create an API key for.

2. Go to API Keys Section

   Navigate to Settings > API Keys in the project menu.

3. Create New Key

   Click the Create API Key button and provide a descriptive name for the key (e.g., “Production Dashboard”, “Analytics Export”).

4. Copy Your Key

   The full API key is only displayed once. Make sure to copy it and store it securely. If you lose it, you’ll need to create a new key.

   Your API key will look like this:

   vem_abcdefghijklmnopqrstuvwxyz123456
   

API Key Format

Vemetric API keys have the following characteristics:

• Prefix: All keys start with vem_
• Length: 36 characters total (including prefix)
• Characters: Lowercase letters (a-z) and numbers (0-9)

Example:

vem_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Making Authenticated Requests

Include your API key in the Authorization header of every request using the Bearer scheme:

Authorization: Bearer vem_your_api_key_here

Example Requests

cURL

curl -X GET 'https://api.vemetric.com/v1/project' \
  -H 'Authorization: Bearer vem_your_api_key_here'

Security Best Practices

API keys provide full access to your project’s analytics data. Treat them like passwords.

Do’s

Store keys securely - Use environment variables or secret management services

Use different keys - Create separate keys for different environments (development, staging, production)

Rotate keys regularly - Periodically revoke old keys and create new ones

Name keys descriptively - Use clear names to track where each key is being used

Don’ts

Never commit keys to version control - Add them to .gitignore or use .env files

Never use keys in client-side code - API keys should only be used in server-side applications

Never share keys - Each team member or service should have its own key

Never log keys - Exclude authorization headers from application logs

Authentication Errors

The API returns specific error codes for authentication issues:

Missing API Key (401)

Request:

curl -X GET 'https://api.vemetric.com/v1/project'

Response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key. Use Authorization: Bearer <key>"
  }
}

Malformed Authorization Header (401)

Request:

curl -X GET 'https://api.vemetric.com/v1/project' \
  -H 'Authorization: vem_your_api_key_here'

Response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Malformed Authorization header. Use Bearer <key>"
  }
}

Invalid API Key Format (401)

Request:

curl -X GET 'https://api.vemetric.com/v1/project' \
  -H 'Authorization: Bearer invalid_key'

Response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key format"
  }
}

Invalid or Revoked API Key (401)

Request:

curl -X GET 'https://api.vemetric.com/v1/project' \
  -H 'Authorization: Bearer vem_this_key_does_not_exist_1234567'

Response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or revoked API key"
  }
}

Managing API Keys

Listing API Keys

You can view all API keys for a project in the dashboard:

1. Navigate to Settings > API Keys
2. You’ll see a list of all keys with:
   • Key name
   • Key prefix (e.g., vem_a1b2c3d4e5...)
   • Creation date
   • Creator

Revoking API Keys

If an API key is compromised or no longer needed:

1. Navigate to Settings > API Keys
2. Click the Revoke button next to the key
3. Confirm the revocation

Revoking a key is immediate and cannot be undone. Any applications using the revoked key will immediately lose access.

Project Scope

Each API key is scoped to a single project. The key only has access to data for that specific project. To access data from multiple projects, you’ll need to create an API key for each project.

The authenticated project is automatically determined from the API key - you don’t need to specify a project ID in your requests.

Next Steps

Now that you have an API key, you can start making requests:

Get Project Info

Retrieve your project’s configuration and settings

Query Analytics

Query analytics data with flexible filters and grouping