​

Authentication

To use the NomadicML API, you need to authenticate your requests using an API key. This page explains how to obtain and use API keys with both the SDK and direct API calls.

​

Obtaining an API Key

You can generate API keys from the NomadicML web platform:

1. Log in to your account at drivemonitor.nomadicml.com
2. Navigate to your profile by clicking your avatar in the top-right corner
3. Select API Keys from the menu
4. Click Generate New Key
5. Enter a name for your key (to help you identify its purpose later)
6. Select the expiration period (default is 90 days)
7. Click Create Key

​

API Key Security

Follow these best practices to keep your API keys secure:

• Never share your API keys publicly
• Don’t commit API keys to source code repositories
• Use environment variables or secure secret management tools
• Set appropriate expiration dates for your keys
• Rotate keys periodically
• Create separate keys for different applications or environments

​

Using API Keys with the SDK

When using the NomadicML Python SDK, provide your API key when initializing the client:

from nomadicml import NomadicML

# Initialize the client with your API key
client = NomadicML(api_key="your_api_key")

# Verify authentication
auth_info = client.verify_auth()
print("Authentication successful:", auth_info)

​

API Key in HTTP Requests

For direct API calls, include your API key in the request headers:

X-API-Key: your_api_key

Example using curl:

curl -X GET "https://api.nomadicml.com/video/status/12345" \
  -H "X-API-Key: your_api_key"

Example using JavaScript fetch:

fetch('https://api.nomadicml.com/video/status/12345', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

​

Verifying Authentication

To verify that your API key is valid and working correctly, use the verification endpoint:

SDK Method:

auth_info = client.verify_auth()
print(auth_info)

HTTP Request:

curl -X POST "https://api.nomadicml.com/api/keys/verify" \
  -H "X-API-Key: your_api_key"

A successful response will include basic information about your account and API key permissions.

​

API Key Permissions

API keys can have different permission scopes:

• read: Access to view videos and analysis results
• write: Permission to upload videos and modify resources
• admin: Full access to all API functionality

By default, new API keys have read and write permissions. If you need admin permissions, contact NomadicML support.

​

Managing API Keys

You can manage your API keys through the web platform:

​

Viewing Keys

The API Keys page shows all your current keys, including:

• Name
• Key prefix (first 8 characters)
• Creation date
• Expiration date
• Last used date
• Status (active/inactive)

​

Revoking Keys

To revoke an API key:

1. Go to the API Keys page
2. Find the key you want to revoke
3. Click the Revoke button
4. Confirm the action

Once revoked, a key cannot be reactivated. You’ll need to generate a new key if needed.

​

Troubleshooting

Common authentication issues:

​

Invalid API Key

If you receive a 401 Unauthorized error:

• Double-check that you’re using the correct API key
• Verify the key hasn’t expired
• Check if the key has been revoked

​

Missing API Key

If you receive a 403 Forbidden error:

• Ensure you’ve included the API key in the request headers
• Check the header format is correct (X-API-Key: your_api_key)

​

Permission Issues

If you receive a 403 Forbidden error with an authorization message:

• Verify that your API key has the necessary permissions for the operation
• Contact NomadicML support if you need additional permissions

​

Next Steps

Now that you understand authentication, explore the API endpoints: