Obtaining and using tokens

Exchange the authorization code for tokens, call the GraphQL API, and refresh access.

After validating the callback, your backend can exchange the authorization code for tokens.

Make this request only from the server. Never send the Client Secret, code_verifier, or tokens to the browser.

Exchange the authorization code for tokens

Send a POST request to:

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

Use the application/x-www-form-urlencoded format:

curl --request POST 'https://api.autentique.com.br/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "client_id=${AUTENTIQUE_CLIENT_ID}" \
  --data-urlencode "client_secret=${AUTENTIQUE_CLIENT_SECRET}" \
  --data-urlencode "redirect_uri=${AUTENTIQUE_REDIRECT_URI}" \
  --data-urlencode "code=${AUTHORIZATION_CODE}" \
  --data-urlencode "code_verifier=${CODE_VERIFIER}"

Use exactly:

• the authorization code received in the callback;

• the code_verifier created at the beginning of the same authorization attempt;

• the same redirect URL sent to the authorization endpoint;

• the credentials for the OAuth application that started the flow.

The response includes:

• access_token;

• refresh_token;

• token_type;

• expiration information.

The access_token lasts 15 days. The refresh_token lasts 365 days.

Store the tokens securely on the server and associate them with the user or organization that authorized the integration.

Call the GraphQL API

Send the access_token as a Bearer token to:

https://api.autentique.com.br/v2/graphql

The following example retrieves the authorized user's data and requires the user:read permission:

curl --request POST 'https://api.autentique.com.br/v2/graphql' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { me { id name email } }"}'

A user may grant fewer permissions than your integration requested. Before relying on an operation, confirm that the required access was granted and handle unauthorized responses.

Refresh the tokens

When the access_token expires, use the refresh_token to obtain a new token pair:

curl --request POST 'https://api.autentique.com.br/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "client_id=${AUTENTIQUE_CLIENT_ID}" \
  --data-urlencode "client_secret=${AUTENTIQUE_CLIENT_SECRET}" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}"

The refresh response returns new access_token and refresh_token values.

Replace both stored values together. After a new refresh_token is issued, do not reuse the previous one.

Prevent two requests from trying to refresh the same tokens at the same time. One common approach is to use a lock for each connection during refresh and release other requests only after the new token pair has been stored.

If refresh fails because the refresh_token expired, was revoked, or has already been replaced, start a new authorization with the user.

Protect the tokens

• Store tokens encrypted or in a service designed for secrets.

• Never put tokens in URLs.

• Do not record complete tokens in logs or analytics tools.

• Limit token access to services that actually call the API.

• Delete tokens when the integration is disconnected.

• Treat tokens as credentials, even when they have an expiration date.

Postman collection

For a practical example, import the OAuth 2.0 collection into Postman:

Download Autentique OAuth 2.0.postman_collection.json

Next operations

With a valid access_token, you can continue to:

• user:read: Fetch current user;

• documents:read: Retrieve a document;

• documents:read: List documents;

• documents:create: Create a document;

• documents:update: Edit a document.

For unexpected responses, see OAuth errors and security.