Zentail authentication flow

Your application gets its access tokens through the OAuth 2.0 authorization-code grant. A seller installs your application in Zentail, Zentail hands you a one-time code, and you exchange that code for a long-lived access token. The flow and the token are the same for v1 and v2: one token calls both.

Three things about this flow surprise people:

One token per seller, per application. Every seller who installs your application starts the flow again and produces a separate token.
There is no refresh grant. A token does not expire on a clock, and there is no way to exchange one for another. If you need a new token, the seller runs the flow again.
The access token is sent verbatim. It goes in the Authorization header with no Bearer prefix.

Before you start

Register your application with Zentail. Registration is arranged with us rather than self-service, and it gives you three things you will need below:

You are issued	What it is for
Client ID	Identifies your application, and arrives on the redirect
Client secret	Authenticates the token exchange over HTTP Basic
Redirect URL	Where Zentail sends the seller, carrying the authorization code

The client ID and secret cannot call the API on their own. They only authenticate the exchange in step 3.

Registration also fixes your application’s scopes. The authorization request takes no scope parameter you can influence — see Scopes.

The flow, step by step

1. The seller installs your application

A Zentail seller (or a Zentail specialist working with them) clicks Install on your application inside Zentail. Zentail checks that your application is registered and active, and the flow begins. You do not initiate it.

2. Zentail redirects the seller to you with a code

Zentail generates a one-time authorization code and redirects the seller’s browser to the redirect URL you registered:

GET <RedirectURL>/?client_id=<client id>&code=<authorization code>

The code is not an access token. Its only use is step 3, and it works once.

At this point, have the seller sign in to your own system, or use their existing session. You need to know which of your accounts the token you are about to receive belongs to.

3. Exchange the code for an access token

From your backend, POST the code to the token endpoint. The request is application/x-www-form-urlencoded and is authenticated with HTTP Basic: your client ID is the username, your client secret is the password.

curl -X POST "https://api.zentail.com/v1/token" \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 -w0)" \
  -d grant_type=authorization_code \
  -d authorization_code=l4b6iplj3r \
  -d redirect_uri=https%3A%2F%2Fyour-domain.example%2Foauth_callback

Three parameters, and all three are required:

grant_type is always authorization_code.
authorization_code is the value from step 2. The parameter is named authorization_code, not code; any other name fails the exchange.
redirect_uri must match the redirect URL you registered, exactly.

A successful exchange answers 200 with the token:

{
  "access_token": "v2podKNZ395VqsQ7dz0afA1T9HpfPQkvoJHHo3Vow4U=",
  "token_type": "bearer"
}

Store access_token against the seller who just installed you. It authorizes calls for that one Zentail account only.

Using the token

Send the access token as the whole Authorization header value, on v1 and v2 routes alike:

curl "https://api.zentail.com/v2/storefront/orders/shipped?lastUpdatedTs=2026-09-22T14%3A00%3A00Z" \
  -H "Authorization: v2podKNZ395VqsQ7dz0afA1T9HpfPQkvoJHHo3Vow4U="

Do not add a Bearer prefix, despite the "token_type": "bearer" in the response. Zentail matches the header against the issued token verbatim, so a prefixed header is rejected.

What the token can then do is decided by the scopes it carries. Scopes lists all of them and the routes each one opens.

There is no refresh grant

Zentail implements no refresh token and no refresh endpoint. Nothing expires on a schedule, so you normally hold one token for the life of the integration.

If a token stops working — the seller uninstalled, or it was revoked — the way to get another is for the seller to install your application again, which runs this flow from step 1.

Seller tokens are a different thing

A seller can also generate a token for themselves, under Settings → API access in Zentail. That token is pasted into the same Authorization header, so it looks interchangeable with the one above. It is not:

A seller token is minted with the single scope legacy, a v1 scope. It lacks the scopes the scoped services require, so they refuse it with a 403.
It belongs to the seller, not to you. You never see it unless the seller sends it to you, and they can regenerate it without telling you.
It carries no application identity, so nothing ties the calls made with it back to your integration.

Seller tokens exist for a seller scripting against their own account. If you are building an application that several sellers install, use the authorization-code flow above. It is the only path that gives you a token per seller, with your application’s scopes.