Authentication

You can call Veza APIs using API keys for authentication. Based on your needs, you can generate personal or team-scoped API keys. Each Personal API Key inherits the permissions of the user who created it, and functions as a personal access token for that user. The Administration > API Keys page allows individual users to manage their own keys under the 'Personal' tab. Only Veza administrators can view keys belonging to other users.

Under the 'Team' tab, you can mange API keys which are scoped to particular teams.

• Users can view the activity status and revoke, reinstate, or rename any keys they create or have permission to update.

• Deleting a key will permanently remove it. Owners can revoke and reinstate keys to intermittently disable them.

• API keys each have a name and owner. Keys inherit the permissions and roles of their creator.

• See User Management for possible Veza admin and operator actions.

Personal API Keys

Personal API keys are used for general platform access and management tasks. Each key is tied to a specific user and is scoped to a single team that the user is a member of.

Create an API Key

To generate a key associated with your user account:

1. Open Administration > API Keys > Personal > Add New Personal API Key.

2. Enter a descriptive name for the new key, and click Save.

3. Copy and save the API key value, which will not be shown again.

Personal API keys are scoped to current user's account and the selected team.

Removing a user from a team will also remove any personal API keys they created within that team.

If a user is removed from the platform, all of their personal API keys will be deleted.

Team API Keys (Early Access)

Team API keys are designed for service accounts that manage Open Authorization API (OAA) integrations assigned to a team. Each key is associated with a single team and has the oaa_push role, restricted to specific read and write operations for creating and updating OAA data sources. These API keys currently cannot be used to access other API endpoints.

Team API keys are visible to all team members but can only be created by users with Admin or Operator roles.

These keys remain within the team even if the user who created them is removed from the team or deleted from the platform.

Creating a Team API Key

1. Open Administration > API Keys > Team > Add New Team API Key.

2. Enter a descriptive name for the new key, and click Save.

3. Copy and save the API key value, which will not be shown again.

Managing API Keys

From the API Keys page, user can also manage the API keys, either personal or team-scoped:

• Use Edit to edit the name of the API key

• Use Revoke to temporarily disable personal API key

• Use Reinstate to reenable a revoked API key

• Use Delete to completely remove the API key

Using API Keys

When making requests to Veza APIs, provide the key as an OAuth 2.0 Bearer Token in the request Authorization header:

curl -X GET 'https://<url>/api/v1/providers/custom' \
-H 'authorization: Bearer <token>'

You should protect and secure API Keys, which have all the permissions associated with your username and password. Save keys as environment variables or use a secrets manager instead of including them in scripts, for example:

import os
import requests

url = os.environ.get('VEZA_API_URL')
access_token = os.environ.get('VEZA_API_KEY')

headers = {
    'authorization': f'Bearer {access_token}'
}

response = requests.get(url, headers=headers)

print(response.json())

Setting up your environment

Where to run API commands

Veza API commands can be executed from any system with command line access (such as Terminal on Mac/Linux, or Command Prompt/PowerShell on Windows).

• You will need internet connectivity to your Veza instance

• The curl command should be available (this is pre-installed on most modern systems for interacting with external web servers and APIs)

The execution environment can be your local workstation, a server or virtual machine in your environment, or any system where IT administrators typically run scripts such as a cloud shell environments (AWS CloudShell, Azure Cloud Shell, etc.).

For non-technical users with more complex automation needs, consider collaborating with your IT team or a developer to execute API scripts, or using graphical API tools like Postman for a more user-friendly interface.

Configuring environment variables

For security and convenience, you should set your API credentials as environment variables rather than including them directly in commands. Examples in this documentation assume the following environment variables are configured:

Windows Command Prompt:

set VEZA_TOKEN=your_api_key_here
set VEZA_URL=https://yourcompany.cookiecloud.ai

Windows PowerShell:

$env:VEZA_TOKEN="your_api_key_here"
$env:VEZA_URL="https://yourcompany.cookiecloud.ai"

Mac/Linux/Unix:

export VEZA_TOKEN="your_api_key_here"
export VEZA_URL="https://yourcompany.cookiecloud.ai"

After setting the variables, verify your configuration with a simple API call:

curl -H "Authorization: Bearer $VEZA_TOKEN" "$VEZA_URL/api/v1/providers"

Successful authentication will return JSON data about your configured providers.

If you encounter errors, verify your API key is correct and has appropriate permissions, confirm your VEZA_URL matches your actual Veza instance URL, and check network connectivity to your Veza instance.

Troubleshooting

If you encounter authentication errors, confirm that the key is valid and generate a new key if required. API key errors are:

• Invalid API key: API key is not the correct format (not base64 encoded)

• Malformed API key: Typically due to a copy and paste error (correct format but invalid characters)