Authorization | Etals | Documentation

Every call your system makes to Etals carries an API token in the Authorization header. A token acts as the user who created it, and its abilities decide which endpoints it may call.

Calls from Etals to your system (the API export) work the other way round: you give Etals a secret to send. That is covered on the export page.

Base URL

Your base URL is the address you sign in to Etals with, for example https://nordvik-outdoor.etals.app. On these pages it is written as https://{your-workspace}.etals.app. All API paths on these pages start with /api/v1.

Headers

Authorization: Bearer {api-token}
Accept: application/json
Content-Type: application/json

Send Accept: application/json on every request. Without it, a missing or rejected token answers with a redirect to the sign-in page, or an HTML error page, instead of a JSON error.

Create a token

Open the API token page

Go to Settings > API Tokens (in the Integrations group of the settings menu). The page needs the permission to manage API tokens (can_manage_api_tokens), which the admin and owner roles have. Without it, the menu entry is hidden.

Fill in Create API token

Name: optional, for example Nordvik PIM sync.
Abilities: tick the ones your integration needs (see the table below).
Special abilities: leave these unticked for integrations. They are for the storefront and public API only, and a token that carries any of them is rejected by the endpoints on these pages.
Allowed origins: leave empty. This list only applies to the public API, not to funnels or feedback.

Generate and copy

Click Generate token and copy the token right away. Etals shows it only once. Afterwards, the token list shows only its last four characters.

The Create API token form with Name "Nordvik PIM sync", Read, Create and Delete ticked, no special abilities and no allowed origins

The New API token dialog: "Copy your new API token now - for security, it won't be shown again." with the token value blurred

Abilities

Ability	Needed for
Create	`POST /api/v1/funnels/{endpoint-url}` and `POST /api/v1/feedback/content-job-values`
Delete	`DELETE /api/v1/funnels/{endpoint-url}`
Read	Lookup endpoints such as `GET /api/v1/languages`, `/markets`, `/brands` and `/fronts`
Update	Not used by the endpoints on these pages

A typical round-trip integration uses one token with Read, Create and Delete.

User permissions

The token can do what its owner can do, within its abilities.

Endpoint	Permission the token’s owner needs
Funnel `POST` and `DELETE`	The manage permission for Funnels (`can_manage_funnels`)
Feedback `POST`	No extra permission

Create integration tokens from a dedicated integration user, not a person’s account. A token always belongs to the user who creates it, so sign in as that user, and give its role the permission to manage API tokens. If the owner is archived or removed, the token is marked Inactive and every request with it is rejected.

Expiry, rotation and revoking

Tokens do not expire.
Rotate creates a new token with the same name and abilities and revokes the old one at once. Update your system right after rotating.
Revoke removes the token. Requests with it fail from then on.

If a token may have leaked, rotate it.

Errors

Situation	HTTP status	Body
Token missing, wrong, revoked, or carrying a special ability	`401`	`{"status": "error", "message": "You are not authorized to access this resource."}`
Token lacks the ability, or the owner lacks the permission	`403`	`{"status": "error", "message": "You are not authorized to perform this action."}`

These bodies assume Accept: application/json.

Example

curl -X POST "https://{your-workspace}.etals.app/api/v1/funnels/nordvik-products" \
  -H "Authorization: Bearer {api-token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "sku": "NV-1003", "name": "Kestrel Down Vest" }'

Keeping tokens safe

Treat a token like a password. Keep it on your server, out of frontend code, repositories, screenshots and tickets.