> For the complete documentation index, see [llms.txt](https://docs.clearout.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clearout.io/developers/oauth-server.md).

# OAuth Server

Official guide to Clearout OAuth 2.1 integration. Learn app registration, PKCE authorization flow, endpoint setup, and secure API access

Clearout's OAuth 2.1 server enables third-party applications to access Clearout services on a user's behalf with their explicit consent, without requiring the user's API key.

{% hint style="info" %}
OAuth is an **authorization** framework, not an authentication protocol. It issues scoped, short-lived access tokens that authorize an application to call approved Clearout APIs. It does not independently establish the identity of the end user.
{% endhint %}

## When to use the OAuth Server

Use OAuth 2.1 when you are building a third-party application that needs to access Clearout on behalf of another Clearout user.

Examples:

* A CRM app that verifies email addresses using the connected user's Clearout credits.
* An automation platform that triggers Clearout workflows after receiving user consent.
* A data-enrichment tool that accesses permitted Clearout services without handling the user's API key.

If you are building an internal integration and already control the Clearout account credentials, use an API key with the Clearout REST API instead.

## Before you begin

Ensure that you have:

* A Clearout account with access to the Developer Console.
* Permission to register an OAuth application.
* At least one redirect URI for your application (use HTTPS in production).
* The Clearout scopes required by your integration.

## Server metadata

Clearout publishes its OAuth endpoints and capabilities at the standard discovery URL. Prefer reading endpoints from here over hard-coding them.

```http
GET https://clearout.io/.well-known/oauth-authorization-server
```

| Endpoint      | URL                                       |
| ------------- | ----------------------------------------- |
| Authorization | `https://app.clearout.io/oauth/authorize` |
| Token         | `https://clearout.io/oauth2/token`        |
| Registration  | `https://clearout.io/oauth2/register`     |

## Register your application

{% stepper %}
{% step %}

### Sign in to Clearout

Open the **Developer Console**.
{% endstep %}

{% step %}

### Create an OAuth app

Go to **OAuth Apps** and select **Create App**.
{% endstep %}

{% step %}

### Enter application details

Enter an application name and choose the application type:

* **Public** — apps that cannot keep a secret (single-page, mobile, desktop, CLI). No client secret is issued.
* **Confidential** — apps with a secure backend. A client secret is issued.

The application type cannot be changed after the app is created.
{% endstep %}

{% step %}

### Add redirect URIs

Add one or more redirect URIs. Each must be an absolute `http://` or `https://` URL; use HTTPS in production.
{% endstep %}

{% step %}

### Select scopes

Select the scopes your application requires. At least one scope is required.
{% endstep %}

{% step %}

### Save the application

Save the application.
{% endstep %}

{% step %}

### Copy the Client ID

Copy the **Client ID** (it starts with `co_`).
{% endstep %}

{% step %}

### Store the Client Secret securely

For **confidential** apps only, copy the **Client Secret** (it starts with `cos_`). It is shown only once — store it securely and never expose it in browser or mobile code. You can rotate it later from the Developer Console; rotating does not disconnect existing users.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Clients can also register programmatically through Dynamic Client Registration (`POST https://clearout.io/oauth2/register`). Clients registered this way are always **public** and receive all supported scopes unless `scope` is specified.
{% endhint %}

## Scopes

Request only the minimum scopes required by your integration.

| Scope          | Allows the application to                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `all_products` | Use Clearout product APIs: email verifier, email finder, reverse lookup, name validation, company lookup, and domain lookup |
| `account`      | Read account information, subscription plans, credits, and service limits                                                   |

Request multiple scopes as a space-separated list, for example `scope=all_products account`. If you omit `scope`, the user is asked to approve every scope your application is registered for.

## Authorization flow

Clearout supports the OAuth 2.1 authorization-code flow with PKCE (`S256` only).

{% stepper %}
{% step %}

### Generate a code verifier

Generate a cryptographically random `code_verifier`.
{% endstep %}

{% step %}

### Create a code challenge

Create a `code_challenge` from the verifier: `BASE64URL(SHA256(code_verifier))`.
{% endstep %}

{% step %}

### Redirect the user

Redirect the user to Clearout's authorization endpoint.
{% endstep %}

{% step %}

### Obtain user consent

The user signs in to Clearout and approves the requested scopes.
{% endstep %}

{% step %}

### Receive the authorization code

Clearout redirects the user to your registered redirect URI with an authorization code. The code is single-use and expires after 10 minutes.
{% endstep %}

{% step %}

### Exchange the authorization code

Exchange the authorization code for an access token.
{% endstep %}

{% step %}

### Call Clearout APIs

Call Clearout APIs using the access token.
{% endstep %}
{% endstepper %}

## Authorization request

Redirect the user to:

```
https://app.clearout.io/oauth/authorize
```

Example:

```http
GET https://app.clearout.io/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=all_products account&
  state=RANDOM_STATE&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256
```

{% hint style="info" %}
URL-encode parameter values in a real request (for example, `scope=all_products%20account`).
{% endhint %}

If the user approves, Clearout redirects to:

```
https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE
```

If the user denies, Clearout redirects to:

```
https://yourapp.com/callback?error=access_denied&state=RANDOM_STATE
```

## Exchange the authorization code

Exchange the authorization code at Clearout's token endpoint.

```
https://clearout.io/oauth2/token
```

The `redirect_uri` must exactly match the one used in the authorization request.

{% tabs %}
{% tab title="Public client" %}

```http
POST https://clearout.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
client_id=YOUR_CLIENT_ID&
code_verifier=CODE_VERIFIER
```

Public clients must **not** send a `client_secret`.
{% endtab %}

{% tab title="Confidential client (Basic auth)" %}

```http
POST https://clearout.io/oauth2/token
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
code_verifier=CODE_VERIFIER
```

{% endtab %}

{% tab title="Confidential client (POST body)" %}

```http
POST https://clearout.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=CODE_VERIFIER
```

{% endtab %}
{% endtabs %}

Example response:

```json
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 604800,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "all_products account"
}
```

| Token              | Lifetime          |
| ------------------ | ----------------- |
| Authorization code | 10 minutes        |
| Access token       | 7 days (604800 s) |
| Refresh token      | 30 days           |

## Call Clearout APIs

Send the access token in the `Authorization` header:

```
Authorization: Bearer ACCESS_TOKEN
```

Example:

```http
POST https://api.clearout.io/v2/email_verify/instant
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "email": "user@example.com"
}
```

Each API requires a specific scope. If the token lacks it, Clearout returns `403 insufficient_scope` with the required scope in the response. APIs outside the OAuth scopes are not available to OAuth access tokens.

## Refresh access tokens

Access tokens expire. When a token expires, use the refresh token to obtain a new access token. Confidential clients must authenticate the same way as in the code exchange.

```http
POST https://clearout.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID
```

You may pass an optional `scope` to request a narrower set of the originally approved scopes.

Follow these rules:

* Store refresh tokens securely.
* Every refresh returns a **new** refresh token and invalidates the old one — always replace the stored token.
* Treat a reused or invalid refresh token as a potential security event.
* Do not request scopes beyond those originally approved by the user; doing so returns `invalid_scope`.

## Revoke access

A Clearout user can disconnect an OAuth application from **Authorized Clients** in their account settings. Revoking access immediately invalidates that connection's access tokens and refresh tokens. If the application owner deletes the OAuth app, access is revoked for every connected user.

Applications should handle authorization failures (`invalid_token`, `invalid_grant`) gracefully and prompt the user to reconnect.

## Security requirements

* Use HTTPS for all redirect URIs in production.
* Use the authorization-code flow with PKCE (`S256`).
* Use an exact redirect URI match.
* Generate a unique `state` parameter for every authorization request and validate it on callback.
* Store client secrets and refresh tokens in a secure secret store.
* Request only the minimum required scopes.
* Do not place access tokens or refresh tokens in URLs, logs, browser storage, or client-side code.

## OAuth errors

### Authorization and token errors

| Error                    | Meaning                                                                                                                                             | Recommended action                    |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `invalid_request`        | A required parameter is missing (`code`, `redirect_uri`, `code_verifier`, or `refresh_token`)                                                       | Fix the request                       |
| `invalid_client`         | Client ID or client secret is missing or invalid, the app was deleted, or a public client sent a secret                                             | Verify app credentials and app type   |
| `invalid_grant`          | Authorization code or refresh token is invalid, expired, reused, revoked, or does not match the client or redirect URI, or PKCE verification failed | Restart authorization or refresh flow |
| `invalid_scope`          | Requested scope is unsupported, not allowed for the app, or exceeds the originally approved scopes                                                  | Request valid scopes                  |
| `unsupported_grant_type` | `grant_type` is not `authorization_code` or `refresh_token`                                                                                         | Use a supported grant type            |
| `access_denied`          | User denied the consent request (returned on the redirect URI)                                                                                      | Show a reconnect or cancellation flow |

### API call errors

These are returned with a `WWW-Authenticate: Bearer` header.

| HTTP status | Error                | Meaning                                                               | Recommended action                       |
| ----------- | -------------------- | --------------------------------------------------------------------- | ---------------------------------------- |
| `401`       | `invalid_token`      | Access token is invalid, expired, or revoked                          | Refresh the token or prompt to reconnect |
| `403`       | `insufficient_scope` | Token lacks the required scope, or the API is not available via OAuth | Request the required scope               |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.clearout.io/developers/oauth-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
