Authenticating to the API

01In a nutshell #sec_36fbfa52

The REVIEWIT API accepts only one authentication mode — OAuth 2.0 client credentials — and only knows machines: there is no way to call the API on behalf of a person.

02A machine identity, never a user #sec_ca4b0dd0

This is a choice, not a limitation to work around. A recertification decision derives all its value from its accountability to a person who has looked, judged, and is responsible for it. A machine identity cannot bear this kind of decision — therefore the API does not allow it, and its authentication mode makes it impossible rather than discouraged.

In practice: the only authorized flow is client_credentials. Flows that assume a user in front of a browser — authorization code, password, implicit — are not activated. A client that attempts them receives a refusal from the token server, not a login page.

03Obtaining a token #sec_02b8bbd6

The call point is POST /connect/token . It expects the standard parameters of the client credentials flow, in application/x-www-form-urlencoded.

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=VOTRE_CLIENT_ID
&client_secret=VOTRE_SECRET
&scope=campaigns.read reviews.read

The response carries an access token and its lifetime.

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The token is then presented on each call, in the Authorization header.

Authorization: Bearer eyJhbGciOi...

04How long a token lasts #sec_4d63dc43

Sixty minutes by default. The value is a deployment setting ( Api:AccessTokenMinutes ): your installation may have shortened it, never lengthened it without the publisher knowing.

Do not request a token per call. The token call point has its own rate limit, lower than that of the data call points: sixty per minute. A client that requests a token with each request exhausts this limit well before the data limit, and finds itself blocked on authentication while its read quota is intact. Keep the token and renew it as it approaches its expiration.

05The token is signed, it is not encrypted #sec_fb3f6e49

The token is a JWT signed by a certificate. It is readable: anyone holding it can read its content — the client identifier, the granted scopes, the expiration date.

This is deliberate. The confidentiality of the transport is ensured by TLS; encrypting the token would add nothing against an attacker who already holds it, and would make diagnostic tools that help understand a refusal unreadable. On the other hand, a leaked token is a usable token: it is treated as a secret until its expiration.

06The scopes #sec_682200d2

A scope is a read or write right on a domain. The token carries only what you request, and the client obtains only what was granted to it at registration: requesting more does not give more.

Four scopes exist without any call point requiring them yet: campaigns.manage, delegations.manage, collect.trigger and deletions.manage. They are declared because the token server knows them, and a client can request them; they do not open any writing today, because the corresponding call points do not exist yet. Requesting them does not break anything and serves no purpose.

07Request as little as possible #sec_00fcfeab

A granted scope remains granted. Request the ones the integration needs, not the ones it might need one day: when the day comes, a scope is added in one line, while a leaked token takes away everything it carried.

08Check what a token carries #sec_b38a4efa

Two diagnostic call points answer the question without having to decode the token by hand.

GET /api/v1/diagnostics/whoami says which client you are and what scopes you carry. GET /api/v1/diagnostics/scope-probe says if a given scope passes the door.

They are used to understand a refusal. A 403 on a data call is diagnosed in three seconds with the first one, and in three hours without it.

09Key points #sec_082cfbe9

One authentication mode, that of machines. A one-hour token, kept and reused. Scopes requested as accurately as possible. And two diagnostic call points that respond before a ticket is opened.