> 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

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