Authentication

Authentication Methods

CargoLint supports two authentication methods: API Keys for server-to-server integration and JWT Bearer Tokens for user-based sessions. Choose the method that best fits your use case.

API Keys (Recommended for Server-to-Server)

Generate an API Key

1. Log in to your CargoLint dashboard
2. Navigate to Settings > API Keys
3. Click Generate New Key
4. Copy your key and store it securely

Using API Keys in Requests

Include your API key in the X-API-Key header:

curl -X GET https://api.cargolint.com/api/v1/documents \
  -H "X-API-Key: cl_test_YOUR_API_KEY_HERE"

import requests

headers = {
    "X-API-Key": "cl_test_YOUR_API_KEY_HERE"
}

response = requests.get(
    "https://api.cargolint.com/api/v1/documents",
    headers=headers
)

Best Practices for API Keys

• Rotate keys regularly for security
• Use environment variables to store keys: CARGOLINT_API_KEY
• Never commit API keys to version control
• Create separate keys for development and production environments
• Revoke keys immediately if compromised

JWT Bearer Tokens (For User Sessions)

Obtaining a JWT Token

Use your credentials to request a token from the login endpoint:

curl -X POST https://api.cargolint.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-secure-password"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

Using JWT Tokens in Requests

Include the access token in the Authorization header with the Bearer scheme:

curl -X GET https://api.cargolint.com/api/v1/documents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Refreshing JWT Tokens

Access tokens expire after one hour. Use the refresh token to obtain a new access token:

curl -X POST https://api.cargolint.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

When to Use Each Method

Method	Use Case	Expiration	Rotation
API Keys	Server-to-server, integrations, microservices	Never (manual revocation)	Manual
JWT Tokens	User sessions, frontend applications, temporary access	1 hour (with refresh tokens)	Automatic

Security Considerations

• API Keys: Best for long-lived, automated processes. Use separate keys per service.
• JWT Tokens: Better for user-facing applications with session management. Automatically expire and require refresh.
• Always use HTTPS when transmitting authentication credentials
• Monitor API activity and set up alerts for unusual access patterns

Need help? Contact our support team.