Skip to content

OAuth 2.0 Authentication

OAuth is where most webservice work stalls, and almost never because IMan is hard to configure. It stalls because the vendor's documentation describes one flow, the application you registered supports another, and the error you get back describes neither.

This page settles which of the two flows a service needs. The recipes are on the three pages after it, each worked end to end against a live service:

For the screen itself — every field, and the full list of %[…] placeholders — see OAuth2 Authentication in the User Guide.

OAuth 1.0 is not supported

IMan supports OAuth 2.0, defined in RFC 6749. OAuth 1.0 is not supported. A service that still offers only OAuth 1.0 — signed requests, a consumer key and a signature method rather than a bearer token — cannot be reached this way.

Which flow do you need?

Vendors rarely use the words "two-legged" and "three-legged". Match on what they describe instead:

What the vendor's documentation says Flow Page
"client credentials"; grant_type=client_credentials; "machine to machine"; "server to server"; "app-only" Two-legged Two-Legged OAuth 2.0
"authorization code"; a redirect URI when you registered the application; "the user will be asked to approve"; a consent screen in the screenshots; offline_access Three-legged Three-Legged OAuth 2.0
"resource owner password"; grant_type=password, with a user name and password among the token parameters Two-legged, as far as IMan is concerned — the credentials simply include a user Two-Legged OAuth 2.0
A single long-lived key, sent on every request, with no token exchange at all Not OAuth Basic Authentication

The reliable tell is the redirect URI. If registering the application asked you for one, the vendor intends to send a browser somewhere and get it back, and that is a three-legged flow. If it did not, there is nobody to ask and no browser step, and the flow is two-legged.

Some services offer both. Prefer two-legged where you have the choice: it needs no human, so it cannot fail six months later because the person who authorised it has left.

Before you start

Have these in front of you. Every one of them comes from the vendor, not from IMan:

  • An application registered with the service, and its client id and client secret. Most vendors show the secret exactly once.
  • The token endpoint, and the shape of the token request — which parameters, and whether they go in the body or in an Authorization header. A curl example in the vendor's documentation is the most reliable source, because it is unambiguous about both.

  • For a three-legged flow, the authorisation endpoint and the scopes, and the Realisable redirect URI registered at the vendor:

    https://authorisation.realisable.co.uk/OAuthCallback

  • One endpoint that answers a GET, to use as the Test URL. It does not have to be the endpoint you intend to integrate with.

What an OAuth object actually describes

Getting this wrong produces an error that points somewhere else entirely.

An OAuth setup does not describe an authentication. It describes several separate HTTP requests, and each has its own section of the configuration pane:

Request Two-legged Three-legged
Send the user to the service to consent — Authorise URL
Get a token Token Request … Token Request …
Renew the token — Refresh Request Form URL Parameters
Every actual call to the API Authenticated API Request Headers Authenticated API Request Headers

The last row is the one that gets missed. Configure everything above it and the token exchange succeeds — and then IMan calls the API carrying no token, and the service answers with a credentials error, because from where it is standing an unauthenticated request is indistinguishable from a badly authenticated one. You go and check the client id and secret. They are fine.

There are no Client ID or Client Secret fields

That is deliberate. You enter the credentials wherever the vendor's documentation puts them — a Basic Authorization header, or client_id and client_secret form parameters — and IMan reads them back out of whichever you used, so %[client_id] and %[client_secret] work either way.

The flow preview

The right-hand pane draws the flow you have configured, from the values you have typed, and redraws as you change them. It is the fastest check on all of the above: if the request that calls the API carries no Authorization header, you can see that before pressing Test rather than after.

It is also honest about what it does not know. %[token] and [credentials] appear as placeholders, because at design time the token does not exist yet.

Verified against IMan 6.1 on 2 September 2026.