Authorizing a user

Send the user to Autentique, request permissions, and validate the authorization response.

In this step, your integration sends the user to Autentique. The user signs in, reviews the requested permissions, and decides whether to grant access.

Before continuing, create an OAuth application and have the following values available:

• the Client ID;

• the registered redirect URL;

• the permissions you will request.

Do not send the Client Secret to the browser. Your backend will use it only when exchanging the authorization code for tokens.

Protect every authorization attempt

Before redirecting the user, create three values:

Value	Purpose
state	Ties the callback to the attempt started by your integration and helps prevent forged requests.
code_verifier	A temporary secret created specifically for that authorization attempt.
code_challenge	A value derived from the code_verifier and sent to Autentique without exposing the original value.

Create new values for every attempt. The code_verifier must contain 43 to 128 characters, and the challenge must use S256.

The following example uses Web Crypto and works in JavaScript runtimes that provide crypto.subtle:

const base64url = (bytes) =>
  btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');

const randomValue = (length = 32) =>
  base64url(crypto.getRandomValues(new Uint8Array(length)));

export async function createOAuthSession() {
  const state = randomValue();
  const codeVerifier = randomValue(64); // 86 characters, within the PKCE limit
  const digest = await crypto.subtle.digest(
    'SHA-256',
    new TextEncoder().encode(codeVerifier),
  );

  return {
    state,
    codeVerifier,
    codeChallenge: base64url(new Uint8Array(digest)),
  };
}

Store state and codeVerifier in a temporary server-side session tied to the user who started the connection. Set a short expiration and remove the session after processing the callback.

If your architecture generates these values in the browser, immediately move them to the temporary server-side session. Do not reuse the values or keep codeVerifier in browser storage.

Build the authorization URL

The authorization endpoint is:

https://api.autentique.com.br/oauth/authorize

Send the following parameters:

Parameter	Value
client_id	The OAuth application's Client ID.
redirect_uri	The URL registered for the OAuth application.
response_type	Use code.
scope	Requested permissions, separated by spaces.
state	The temporary value created by your integration.
code_challenge	The challenge derived from the code_verifier.
code_challenge_method	Use S256.

Example:

const url = new URL('https://api.autentique.com.br/oauth/authorize');
url.search = new URLSearchParams({
  client_id: process.env.AUTENTIQUE_CLIENT_ID,
  redirect_uri: process.env.AUTENTIQUE_REDIRECT_URI,
  response_type: 'code',
  scope: 'user:read documents:read',
  state: oauthSession.state,
  code_challenge: oauthSession.codeChallenge,
  code_challenge_method: 'S256',
  // prompt: 'consent',
}).toString();

return url.toString();

The scope value must contain only permissions configured for the OAuth application. Separate multiple permissions with spaces.

Use prompt=consent only when you need to display the consent screen again.

Redirect the user's browser to the generated URL. Do not make an AJAX request to the authorization endpoint.

Receive the callback

After the user makes a decision, Autentique redirects the browser to the registered URL.

If access is approved, the callback contains code and state:

https://app.example.com/integrations/autentique/callback?code=CODE&state=VALUE

Before using the authorization code:

1. Find the temporary session for that authorization attempt.

2. Compare the returned state with the stored value.

3. Confirm that the session has not expired.

4. Remove the session or mark it as used.

If state is missing or does not match, end the attempt. Do not exchange the authorization code for tokens.

The authorization code is temporary, single-use, and tied to the OAuth application, redirect URL, and code_verifier for that attempt.

Handle denied authorization

If the user denies access or authorization cannot be completed, the callback may contain:

• error;

• error_description;

• state.

For example:

https://app.example.com/integrations/autentique/callback?error=access_denied&state=VALUE

Validate state for error responses as well. Then tell the user that the connection was not completed and let them try again if they choose.

Do not treat a denial as an unexpected failure or automatically start another authorization attempt.

After validating the callback, continue to Obtaining and using tokens.