Getting started
Authentication
Create an Etchv API key with only the permissions your integration needs, keep it on your server, and fix common API authentication errors.
Send your API key in the X-API-Key header. Store it in your server’s secret
manager, a tool that keeps passwords and keys safe.
curl https://api.etchv.com/watermarks/images/detect \
-H "X-API-Key: $ETCHV_API_KEY" \
-F 'file=@watermarked.png'Create a key
- Open API keys and select your organization.
- Choose only the permissions (scopes) your integration needs.
- Copy the secret or download its CSV before you close the confirmation screen. Etchv shows it only once.
| Scope | Permission |
|---|---|
watermarks:embed | Watermark images, PDFs and video |
watermarks:detect | Detect watermarks in supported media |
assets:read | List, inspect and download assets |
assets:write | Rename assets and replace metadata |
assets:delete | Delete assets; owner/admin membership also required |
webhooks:read | Inspect endpoints and deliveries |
webhooks:write | Manage endpoints and redeliver events; owner/admin only |
storage:read | Inspect destinations, deliveries and downloads |
storage:write | Manage/verify connections, move results and retry delivery; owner/admin only |
watermarks:embed- Permission
- Watermark images, PDFs and video
watermarks:detect- Permission
- Detect watermarks in supported media
assets:read- Permission
- List, inspect and download assets
assets:write- Permission
- Rename assets and replace metadata
assets:delete- Permission
- Delete assets; owner/admin membership also required
webhooks:read- Permission
- Inspect endpoints and deliveries
webhooks:write- Permission
- Manage endpoints and redeliver events; owner/admin only
storage:read- Permission
- Inspect destinations, deliveries and downloads
storage:write- Permission
- Manage/verify connections, move results and retry delivery; owner/admin only
Each key belongs to one Organization. On every request, Etchv checks Organization membership, whether the key has expired or been revoked, and the key's permissions. To process files, your plan must include the format and you need available credits.
Use keys in the dashboard
The media forms pick an active key from your Organization. Use the dropdown to change it. Keys without the required scope are disabled. Members can select their own keys. Owners and admins can select any Organization key. Your choice lasts until you close the browser session.
You are already signed in, so you don't need to paste a secret. The API examples you can copy match the media, request mode and storage you selected.
Keep credentials on your server
Do not put keys in frontend code, mobile apps, public code repositories or URLs. If a key is exposed, revoke it and create a new one.
Authentication errors
| Status | Check |
|---|---|
401 | Missing, invalid, expired or revoked key |
403 | Scopes, membership or plan access |
402 | Billing and available credits |
401- Check
- Missing, invalid, expired or revoked key
403- Check
- Scopes, membership or plan access
402- Check
- Billing and available credits
Check a key without spending credits
GET accepts any active key in X-API-Key. It returns
organization_id, key_id and scopes, with Cache-Control: no-store.
It uses no credits and gives no extra permissions.
Job permissions and management access
A job can use an existing webhook or verified storage destination with only its embed or detect scope. Managing those resources needs the scopes above. Managing assets uses no watermarking credits.
Managing your account and Organization needs a signed-in session. API keys cannot do this. Webhooks · Storage.