Confirming a client

A client record and a real website are two separate things. Creating the client gives you a key and a secret; confirmation is what ties that record to the site where those credentials are entered. Until it happens the client takes no part in the exchange – your content is offered to nobody, and the blocks on your pages stay empty.

Nothing in the dashboard starts it, and there is no button here to press. Confirmation begins on the site side, the moment the credentials are saved there.

The setup guide

The client's page has a Setup guide button, and the guide opens on its own right after a new client is created. It points at one field at a time and says what to do with it, and it carries the key and the secret along – both can be copied from the guide itself, which matters because it covers the card underneath while it is open.

Closing it loses nothing. Press the button again whenever you want the steps back.

The four steps

1. Install an integration on your site. The first step lists what is available: the official WordPress plugin, a Drupal module still in development, and your own code against the REST API for every other platform.
2. Copy the API key. This is the public half of the pair that identifies your site. In the WordPress plugin it goes into the API key field, under Traffman → Settings → API.
3. Copy the API secret. The secret is the half that proves the site is yours, so it stays masked on the client page – copying it does not reveal it. Paste it next to the key, into the API secret field.
4. Press Save in the plugin. That is the whole of it: the verification starts from there.

What our server does

Saving sends us the key together with the address of a callback endpoint on your site, signed with the secret. That signature proves whoever is asking knows the secret – it does not yet prove the site is the one asking. So our server turns around and calls that address back, with a one-off token the site has to sign with the same secret and return. Only when the answer matches is the client confirmed.

The callback runs in a queue rather than during the save, so it takes a few minutes; the plugin says as much in the notice it shows.

When it succeeds, three things change at once:

• the Host field on the client page fills with the address of the connected site – it is taken from that callback address, which is why it stays empty until now;
• the client is activated and its status becomes Active – if your subscription has room for another active client (see below);
• a confirmation email arrives.

The statuses

Awaiting confirmation is a client with no site behind it yet – the state every client starts in. Active is a confirmed client taking part in the exchange.

A confirmed client can be deactivated as well, and its status says why:

• Deactivated: subscription limit – the client does not fit your subscription's limit of active clients: you can create more clients than the limit, but only that many can be active at once. A client confirmed when the limit is already used up is not activated; after a move to a lower subscription the newest clients above the limit are deactivated, and an email says so. Such a client is activated again automatically after an upgrade – or deactivate another client on its edit page and activate this one.
• Deactivated – you deactivated the client yourself, on its edit page. It stays deactivated whatever happens to the subscription, until you activate it again.

A deactivated client keeps its host but takes no part in the exchange.

One site, one client

The host is what makes a client unique, and it comes from the site that confirmed it. Two things follow from that:

• The same credentials cannot be used on a second site. Once the client is confirmed, saving its key and secret anywhere else is answered with "Mismatch between client host and callback URL host."
• A site that already has a confirmed client cannot confirm another one on top of it: "The client host is already in use."

So every site you bring into the network needs its own client, and each client stays with its site for good. If your site moves to another domain, write to us rather than pressing Save again.

When nothing arrives

A failed verification is silent: no email, and the status simply stays Awaiting confirmation. It is not retried on its own either – our server called once and got no usable answer. Starting it over is the same Save button on the API tab, with the same key and secret.

Before pressing it again, it is worth learning what went wrong. The plugin's Healthcheck tab asks our server to call your site on the spot and prints the reason it failed; both of its buttons are described in installing the plugin.

By far the most common reason is that our server never reached your site at all – hosting bot protection, a firewall or a CDN answered it with a captcha instead of the page. When hosting protection blocks our server lists the names that option hides behind and how to let our address through.

Pressing Save several times in a row runs into a rate limit: "You can request client confirmation again in N seconds." It means nothing is broken – wait out the seconds and press it once.

We remind you

A client left unconfirmed is not forgotten. A reminder arrives a week after it was created, then after a month, three months, six months and a year, until the client is either confirmed or deleted; one email covers every unconfirmed client of the account at once.

With the client active, what is left is on the site side: choose the content it offers to the network and place a block where borrowed content should appear.