Skip to content

Web Users: OAuth Authentication

A web user whose authentication type is oAuth 2.0 is an OAuth client. It uses its client id and secret to obtain an access token from the IMan Authorisation Service (the client credentials grant). It then presents that token as a bearer token on every request to the WebAPI. Nothing about the endpoint changes: the user still has to be assigned to it.

User Setup

You create the user like any other, with these differences.

Display Name

In place of Web User Id: the name the Authorisation Service shows for the client. It is still the value of Http.User.UserId in the integration.

Client Id

In place of User Token: the client_id of the token request. IMan generates it when you create the user.

The Add New Record dialog for a web user with Http Authentication Type oAuth 2.0: Display Name Visionaire, Client Id, Request Throttling None and Enabled ticked

Client Secret

When you save a new user, IMan registers the client with the Authorisation Service and shows its secret once. Copy the secret and pass it to the caller over a secure channel. IMan cannot show it again.

The OAuth2 Partner Credentials dialog: a warning to capture the client_secret now, the secret in a box with a copy button, and a Done button

Rotating the secret

Edit the user, press Regenerate under Client Secret and confirm. IMan shows the new secret once, as before. Tokens already issued stay valid until they expire, so the caller has up to fifteen minutes to switch.

The Edit Web User dialog for the oAuth 2.0 user Visionaire: Client Id, then under Client Secret a confirmation, Regenerate OAuth2 secret?, with Regenerate and Cancel buttons

SSL Certificate Requirements

Tokens travel in request headers, so the WebAPI must be served over HTTPS. Bind the IIS site that hosts IManWebAPI (typically Default Web Site) to a valid SSL certificate on the port callers use (typically 443). Setup does not do this for you.

  1. Add the certificate to the server through Manage Computer Certificates.
  2. In IIS Manager select the site (purple) and open Bindings (blue).
  3. Select the https binding on 443 and Edit it, or Add one (orange).
  4. Choose the certificate under SSL certificate (green).

IIS Manager with Default Web Site selected, the Site Bindings list, and the Edit Site Binding dialog for https on port 443 with RealisableHttpsCertificate chosen, with the callouts Default Website, Select or Add Port and Select Certificate

Obtaining and Using a Token

A sequence diagram: the client posts its credentials to the authorization server's token endpoint, receives a signed JWT, calls the IMan WebAPI with it as a bearer token, and receives the protected resource

  1. Request a token from the Authorisation Service. Its token endpoint is /connect/token on the service's own port (44390 on a default install). The body is form-encoded.

    POST https://<imanserver>:44390/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<Client Id>&client_secret=<Client Secret>&scope=httpListener_scope

  2. A successful response is JSON holding the token and its lifetime in seconds.

    {
  "access_token": "eyJhbGciOiJSU...",
  "token_type": "Bearer",
  "expires_in": 899
}

    A token lasts fifteen minutes. Request a new token when the old one expires, not one per call. The token endpoint accepts ten requests a minute from one address.

  3. Call the WebAPI with the token in the Authorization header. You do not need an X-User-Token header, because the token carries the client id.

    GET https://<imanserver>/IManWebAPI/orders?from=2026-04-01
Authorization: Bearer eyJhbGciOiJSU...
Accept: application/json

A 401 with WWW-Authenticate: Bearer means the WebAPI did not accept the token. Either the token has expired, it was issued to a client that is not assigned to the endpoint or the user is disabled.