> For the complete documentation index, see [llms.txt](https://docs.autentique.com.br/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autentique.com.br/api/integration-basics/oauth2/obtaining-and-using-tokens.md).

# 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:

```bash
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:

```bash
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:

```bash
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](https://469185076-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LXffZ8FZep2ukRK-gJz-887967055%2Fuploads%2FphJ3gz5t9D0ZnY9a2PpM%2FAutentique%20OAuth%202.0.postman_collection.json?alt=media\&token=cea5b561-8cdc-4a95-b21f-5024671a11ac)

### 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**.
