> 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.md).

# OAuth 2.0

OAuth 2.0 lets a user authorize your integration to access specific Autentique data without sharing their account password.

Your system requests permission to access your user's Autentique account by sending them to an Autentique page, where they review the requested permissions and decide what to authorize. Your integration receives tokens that let it call the API only within the granted permissions. Access can later be stopped by revoking the OAuth application.

### When to use OAuth

Use OAuth when other Autentique users or organizations will use your integration.

For example, a management platform can let each customer connect their own Autentique account. After authorization, the platform can retrieve or create documents on that customer's behalf, according to the permissions they granted.

If you only need to integrate an account you control, an API key may be simpler.

| Access method | Recommended for                                                                   |
| ------------- | --------------------------------------------------------------------------------- |
| API key       | Internal integrations that access the account the key belongs to.                 |
| OAuth 2.0     | Applications used by different users, who authorize access to their own accounts. |

OAuth is an authorization protocol. Your integration does not receive the user's password and must never ask them to enter their Autentique credentials anywhere outside Autentique's own pages.

### How it works

Autentique uses the Authorization Code flow with PKCE:

1. Your integration creates temporary security values and sends the user to Autentique.
2. The user signs in, reviews the requested permissions, and approves or denies access.
3. Autentique redirects the user to the URL registered for the OAuth application.
4. If access is approved, your integration receives a single-use authorization code.
5. Your backend exchanges that code for an `access_token` and a `refresh_token`.
6. The `access_token` calls the GraphQL API. When it expires, the `refresh_token` obtains new tokens without asking the user to authorize again.

The authorization code passes through the browser, but credentials and tokens must remain protected on the server.

### Who participates in the flow

| Participant      | What they do                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| User             | Decides whether the integration may access their account and which permissions to grant.        |
| Your integration | Starts authorization, receives the callback, and uses tokens to call the API.                   |
| Autentique       | Authenticates the user, displays the consent screen, and issues authorization codes and tokens. |

### Before you begin

This guide assumes your application has a backend that can:

* store the Client Secret and tokens securely;
* create a temporary session for each authorization attempt;
* receive the callback from Autentique;
* make HTTPS requests to the API.

Do not put the Client Secret, `access_token`, or `refresh_token` in browser JavaScript, a mobile application, a repository, a log, or an analytics tool. That is how preventable security incidents happen.

### Next steps

1. Create an OAuth application from the Applications page in the Autentique dashboard.
2. Implement user authorization.
3. Obtain and use the tokens.
4. Review OAuth errors and security before releasing your integration.