Authentication

How access to the Clipzy ML Engine API is controlled and how to pass credentials.

How access is controlled

Clipzy ML Engine does not implement API key authentication in the application layer. Access is instead enforced at the network and infrastructure level—typically via a reverse proxy, VPN, or firewall that restricts which clients can reach the API host.

CORS is configured server-side using the CORS_ORIGINS environment variable, which controls which browser origins are permitted to make cross-origin requests.

Contact your administrator to obtain access credentials or to confirm the authentication scheme used in your deployment.

Passing a Bearer token

Some deployments place an authentication proxy in front of Clipzy that requires a Bearer token. If your deployment uses one, include an Authorization header on every request.

curl https://your-api-host/api/v1/jobs \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "video_id": "vid_abc123" }'

Replace YOUR_TOKEN with the token provided by your administrator.

Store your token in an environment variable rather than hardcoding it.

export CLIPZY_TOKEN="your_token_here"

curl https://your-api-host/api/v1/jobs \
  -H "Authorization: Bearer $CLIPZY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "video_id": "vid_abc123" }'

Auth error response format

When a request is rejected for authentication or authorization reasons, the API returns an error response in this format:

{
  "success": false,
  "message": "Unauthorized",
  "error": {
    "detail": "Missing or invalid authentication credentials.",
    "code": "UNAUTHORIZED"
  }
}

All error responses follow the same structure:

Field	Type	Description
success	boolean	Always false for errors.
message	string	Human-readable summary of the error.
error.detail	string	Technical detail about the failure.
error.code	string	Machine-readable error code.

Common auth-related HTTP status codes:

Status	Meaning
401 Unauthorized	No valid credentials were provided.
403 Forbidden	Credentials were valid but access to the resource is denied.

CORS configuration

If you are calling the API from a browser, your origin must be included in the server’s CORS_ORIGINS allowlist. Contact your administrator to add your origin. CORS restrictions do not apply to server-to-server requests.