Skip to content

Authentication

LexOpti is an OAuth 2.1 authorization server. Your application acts for one member in one organization: the member chooses the organization while authorizing, and every token is bound to it. To connect a member step by step, follow build a complete integration.

Use Value
Issuer https://app.lexopti.com/api/auth
Metadata https://app.lexopti.com/.well-known/oauth-authorization-server/api/auth
Authorization GET https://app.lexopti.com/api/auth/oauth2/authorize
Token POST https://app.lexopti.com/api/auth/oauth2/token
Revocation (RFC 7009) POST https://app.lexopti.com/api/auth/oauth2/revoke, with token and token_type_hint
API resource https://app.lexopti.com/v1

A web application’s client is confidential: it authenticates at the token and revocation endpoints with HTTP Basic (client_secret_basic, id and secret form-encoded). A mobile or desktop app is registered as a native app, a public client without a secret that sends its client_id in the form (mobile and native apps).

Authorization code with PKCE (S256, always required). Request the resource https://app.lexopti.com/v1 at the authorization and at the token endpoint. A web application’s redirect URIs are exact HTTPS URLs, no wildcard; a native app’s are a loopback IP literal on any port, a reverse-domain private-use scheme or a claimed HTTPS URI (register a native app).

Grant Parameters at the token endpoint
authorization_code code, code_verifier, redirect_uri, resource
refresh_token refresh_token, resource

LexOpti’s sign-in page offers No account yet? Create one below its form, and an e-mail address LexOpti does not know leads there too. The member follows LexOpti’s normal sign-up: profession, organization, offer or free trial, payment when needed, and the code sent to their e-mail. The page tells them that if their organization already uses LexOpti, they should ask their manager for an invitation rather than create a second one.

Your authorization request is kept for 45 minutes, in that browser only. Once the sign-up is done, or the invitation accepted, the member goes on with it (the organization choice when they have several, then the consent) and comes back to your redirect_uri with the code and your state, as after a sign-in. Nothing changes on your side: the same request, the same callback, the same state check. Past 45 minutes, or in another browser, the account is still created but the member stays in LexOpti: they start the connection again from your software.

An application still limited to sandboxes stays so: a new member’s organization is a real one, which it cannot be authorized for.

Once an organization has installed your application for all its members, it may let your software act for the members it enrolled without their own sign-in: the delegated mode, on by default for an installed application, which the organization asks LexOpti to switch off or on. Your software then keeps one connection, an owner’s or admin’s, and names the acting member on each request with the header X-LexOpti-Acting-User: <member_id>. LexOpti runs the request with that member’s role and records, on every trail, that the identity was asserted by your application. Enrolment, the two modes and their refusals: enrol your members.

Scope Grants
lexopti:read read the organization, clients, checks, cases, alerts, events, usage and webhook endpoints
lexopti:write create clients, launch checks, review alerts, manage webhooks, open embed sessions and deep links
offline_access a refresh token
openid, email the member’s identity

A member with a read-only role in the organization can never write, whatever the scopes (readonly_member).

  • Access tokens live 15 minutes. Refresh them automatically, before they expire or when you get a 401: with the SDK, accessToken is a function called once per operation, which returns a valid token and refreshes it when needed.
  • Refresh tokens live 30 days and rotate at every use: each refresh returns a new refresh token, valid 30 days from then. Concurrent refreshes within 10 seconds are tolerated (the same response is returned); replaying an old refresh token later is treated as theft and revokes the whole family: store the new refresh token atomically.
  • An application left unused for 30 days, its last refresh token expired, needs a new authorization from the member: send them through the authorization flow again.
  • A refresh token is also revoked, whatever its expiry, when access ends (below): the member leaves the organization or is banned, the organization blocks your application, LexOpti disables it, the member withdraws their consent, or a replayed refresh token revoked its family.
  • Your client secret is shown once and stored hashed. Ask LexOpti to rotate it: the new secret is shown once, and the previous one keeps working for 24 hours, so deploy the new one within that window, without downtime.

A refresh at the token endpoint, with HTTP Basic: store the new refresh token before you use the access token.

/** New tokens for a refresh token: store the refresh token it answers. */
async function
function refreshTokens(refreshToken: string): Promise<{
access_token: string;
expires_in: number;
refresh_token: string;
}>

New tokens for a refresh token: store the refresh token it answers.

refreshTokens
(
refreshToken: string
refreshToken
: string) {
const
const basic: string
basic
=
var Buffer: BufferConstructor
Buffer
.
BufferConstructor.from(string: WithImplicitCoercion<string>, encoding?: BufferEncoding): Buffer<ArrayBuffer> (+3 overloads)

Creates a new Buffer containing string. The encoding parameter identifies the character encoding to be used when converting string into bytes.

import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('latin1'));
// Prints: this is a tést

A TypeError will be thrown if string is not a string or another type appropriate for Buffer.from() variants.

Buffer.from(string) may also use the internal Buffer pool like Buffer.allocUnsafe() does.

@since ― v5.10.0

@param ― string A string to encode.

@param ― encoding The encoding of string. Default: 'utf8'.

from
(
`${
function encodeURIComponent(uriComponent: string | number | boolean): string

Encodes a text string as a valid component of a Uniform Resource Identifier (URI).

@param ― uriComponent A value representing an unencoded URI component.

encodeURIComponent
(
const clientId: string
clientId
)}:${
function encodeURIComponent(uriComponent: string | number | boolean): string

Encodes a text string as a valid component of a Uniform Resource Identifier (URI).

@param ― uriComponent A value representing an unencoded URI component.

encodeURIComponent
(
const clientSecret: string
clientSecret
)}`
).
Buffer<ArrayBuffer>.toString(encoding?: BufferEncoding, start?: number, end?: number): string

Decodes buf to a string according to the specified character encoding inencoding. start and end may be passed to decode only a subset of buf.

If encoding is 'utf8' and a byte sequence in the input is not valid UTF-8, then each invalid byte is replaced with the replacement character U+FFFD.

The maximum length of a string instance (in UTF-16 code units) is available as

constants.MAX_STRING_LENGTH

.

import { Buffer } from 'node:buffer';
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde
const buf2 = Buffer.from('tést');
console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té

@since ― v0.1.90

@param ― encoding The character encoding to use.

@param ― start The byte offset to start decoding at.

@param ― end The byte offset to stop decoding at (not inclusive).

toString
("base64");
const
const response: Response
response
= await
function fetch(input: string | URL | Request, init?: RequestInit): Promise<Response> (+1 overload)
fetch
(
"https://app.lexopti.com/api/auth/oauth2/token",
{
RequestInit.body?: BodyInit | null | undefined

A BodyInit object or null to set request's body.

body
: new
var URLSearchParams: new (init?: string[][] | Record<string, string> | string | URLSearchParams) => URLSearchParams

The URLSearchParams interface defines utility methods to work with the query string of a URL.

MDN Reference

URLSearchParams class is a global reference for import { URLSearchParams } from 'node:url' https://nodejs.org/api/url.html#class-urlsearchparams

@since ― v10.0.0

URLSearchParams
({
grant_type: string
grant_type
: "refresh_token",
refresh_token: string
refresh_token
:
refreshToken: string
refreshToken
,
resource: string
resource
: "https://app.lexopti.com/v1",
}),
RequestInit.headers?: HeadersInit | undefined

A Headers object, an object literal, or an array of two-item arrays to set request's headers.

headers
: {
authorization: string
authorization
: `Basic ${
const basic: string
basic
}` },
RequestInit.method?: string | undefined

A string to set request's method.

method
: "POST",
}
);
if (!
const response: Response
response
.
Response.ok: boolean

The ok read-only property of the Response interface contains a Boolean stating whether the response was successful (status in the range 200-299) or not.

MDN Reference

ok
) {
// invalid_grant: the member must authorize again.
throw new
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error
(`The token endpoint answered ${
const response: Response
response
.
Response.status: number

The status read-only property of the Response interface contains the HTTP status codes of the response.

MDN Reference

status
}`);
}
const
const tokens: {
access_token: string;
expires_in: number;
refresh_token: string;
}
tokens
: {
access_token: string
access_token
: string;
expires_in: number
expires_in
: number;
refresh_token: string
refresh_token
: string;
} = await
const response: Response
response
.
Body.json(): Promise<any>
json
();
return
const tokens: {
access_token: string;
expires_in: number;
refresh_token: string;
}
tokens
;
}

When the member disconnects LexOpti in your software, revoke their tokens at the revocation endpoint with HTTP Basic: first the refresh token, which ends the grant, then the access token. Drop the tokens even if a revocation fails.

const
const basic: string
basic
=
var Buffer: BufferConstructor
Buffer
.
BufferConstructor.from(string: WithImplicitCoercion<string>, encoding?: BufferEncoding): Buffer<ArrayBuffer> (+3 overloads)

Creates a new Buffer containing string. The encoding parameter identifies the character encoding to be used when converting string into bytes.

import { Buffer } from 'node:buffer';
const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('latin1'));
// Prints: this is a tést

A TypeError will be thrown if string is not a string or another type appropriate for Buffer.from() variants.

Buffer.from(string) may also use the internal Buffer pool like Buffer.allocUnsafe() does.

@since ― v5.10.0

@param ― string A string to encode.

@param ― encoding The encoding of string. Default: 'utf8'.

from
(
`${
function encodeURIComponent(uriComponent: string | number | boolean): string

Encodes a text string as a valid component of a Uniform Resource Identifier (URI).

@param ― uriComponent A value representing an unencoded URI component.

encodeURIComponent
(
const clientId: string
clientId
)}:${
function encodeURIComponent(uriComponent: string | number | boolean): string

Encodes a text string as a valid component of a Uniform Resource Identifier (URI).

@param ― uriComponent A value representing an unencoded URI component.

encodeURIComponent
(
const clientSecret: string
clientSecret
)}`
).
Buffer<ArrayBuffer>.toString(encoding?: BufferEncoding, start?: number, end?: number): string

Decodes buf to a string according to the specified character encoding inencoding. start and end may be passed to decode only a subset of buf.

If encoding is 'utf8' and a byte sequence in the input is not valid UTF-8, then each invalid byte is replaced with the replacement character U+FFFD.

The maximum length of a string instance (in UTF-16 code units) is available as

constants.MAX_STRING_LENGTH

.

import { Buffer } from 'node:buffer';
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
// 97 is the decimal ASCII value for 'a'.
buf1[i] = i + 97;
}
console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde
const buf2 = Buffer.from('tést');
console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té

@since ― v0.1.90

@param ― encoding The character encoding to use.

@param ― start The byte offset to start decoding at.

@param ― end The byte offset to stop decoding at (not inclusive).

toString
("base64");
// The refresh token first: it ends the grant. Then the access token.
for (const [
const token: string
token
,
const hint: "refresh_token" | "access_token"
hint
] of [
[
const tokens: {
access_token: string;
refresh_token: string;
}
tokens
.
refresh_token: string
refresh_token
, "refresh_token"],
[
const tokens: {
access_token: string;
refresh_token: string;
}
tokens
.
access_token: string
access_token
, "access_token"],
] as
type const = readonly [readonly [string, "refresh_token"], readonly [string, "access_token"]]
const
) {
await
function fetch(input: string | URL | Request, init?: RequestInit): Promise<Response> (+1 overload)
fetch
("https://app.lexopti.com/api/auth/oauth2/revoke", {
RequestInit.body?: BodyInit | null | undefined

A BodyInit object or null to set request's body.

body
: new
var URLSearchParams: new (init?: string[][] | Record<string, string> | string | URLSearchParams) => URLSearchParams

The URLSearchParams interface defines utility methods to work with the query string of a URL.

MDN Reference

URLSearchParams class is a global reference for import { URLSearchParams } from 'node:url' https://nodejs.org/api/url.html#class-urlsearchparams

@since ― v10.0.0

URLSearchParams
({
token: string
token
,
token_type_hint: "refresh_token" | "access_token"
token_type_hint
:
const hint: "refresh_token" | "access_token"
hint
}),
RequestInit.headers?: HeadersInit | undefined

A Headers object, an object literal, or an array of two-item arrays to set request's headers.

headers
: {
authorization: string
authorization
: `Basic ${
const basic: string
basic
}` },
RequestInit.method?: string | undefined

A string to set request's method.

method
: "POST",
});
}
// Then drop the tokens, even if a revocation failed.

Every request re-checks that the member still belongs to the organization, is not banned, that the organization has not blocked your application, that LexOpti has not disabled it, and that the member’s consent still exists. Any of these gone: the next request answers 401 invalid_token, whatever the token’s expiry. A token never acts beyond the member’s current consent: a consent narrowed to fewer scopes narrows the tokens already issued.

Test Request in the API reference and the live preview of the playground sign you in with the portal’s own application, for one of your sandboxes only, and keep the token in the page’s memory, never in the browser’s storage. The playground opens the authorization in a window; when the browser blocks it, when it is closed without an answer or takes too long, or when you choose Open in this tab, it continues in the same tab and brings you back to the playground with its settings. The API reference can only use a window, as its viewer offers no other way: if your browser blocks it, allow pop-ups for the portal, or paste an access token under Authentication.