Authentication

The Envoy AI API supports two authentication methods. Choose the one that fits your use case.

Bearer token

Bearer tokens are short-lived JWTs for interactive sessions. Use them when building user-facing applications or testing from the dashboard.

Obtain a token by calling the login endpoint:

$
curl -X POST https://tryenvoy.ai/api/v1/auth/login \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "email": "[email protected]",
>
    "password": "your-password"
>
  }'

The response includes an access_token:

1
{
2
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
3
  "token_type": "bearer"
4
}

Include it in subsequent requests using the Authorization header:

$
curl https://tryenvoy.ai/api/v1/loads \
>
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

API key

API keys are long-lived credentials for programmatic access. Use them for TMS integrations, automated pipelines, and server-to-server communication. Each key is scoped to your organization.

Create an API key through the dashboard or via the API:

$
curl -X POST https://tryenvoy.ai/api/v1/api-keys \
>
  -H "Authorization: Bearer <access_token>" \
>
  -H "Content-Type: application/json" \
>
  -d '{"name": "TMS Integration"}'

The key value is returned once in the response. Store it securely — it cannot be retrieved again.

Include it in requests using the X-API-Key header:

$
curl https://tryenvoy.ai/api/v1/loads \
>
  -H "X-API-Key: envai_live_abc123..."

When to use each method

Security best practices

• Rotate API keys regularly. Use the regenerate endpoint to issue a new key without downtime.
• Never expose keys in client-side code. API keys belong on your server, not in browser JavaScript or mobile apps.
• Set expiration dates on keys used for time-limited integrations.
• Use separate keys for separate integrations. This limits blast radius if a key is compromised.
• Deactivate unused keys immediately via DELETE /api-keys/{id}.