> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.omnisend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

We support the OAuth [Authorization Code](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1) Grant flow for 2026-03-15 endpoints.
If you would like to use it please fill in the following form <https://forms.gle/axz6ychcELUuPrR28> and we will get back to you with oAuth credentials in 1-3 business days.

## Usage

### 1. Generating an auth request

| Query parameter | Description                                                                                                                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type` | Authorization code grant type. Always pass `code`.                                                                                                                                                       |
| `client_id`     | Your OAuth client id.                                                                                                                                                                                    |
| `redirect_uri`  | URL where user will be redirected with generated auth code.                                                                                                                                              |
| `scopes`        | The resources your app is willing to access. Values separated by spaces. They are defined for each endpoint in our API documentation.                                                                    |
| `state`         | Randomly generated, unique per request value used by your app to maintain state between request and callback. More info: ["state" Parameter](https://datatracker.ietf.org/doc/html/rfc6819#section-3.6). |

E.g.:

```http
GET https://app.omnisend.com/oauth2/authorize?client_id=YOUR_CLIENT_ID
&redirect_uri=REDIRECT_URI
&response_type=code
&state=RANDOMLY_GENERATED_VALUE
&scope=RESOURCEX%20RESOURCEY
```

If a user is not logged in, she/he will be redirected to do that. After logging in, the consent page will be shown.

<img src="https://storage.googleapis.com/omnisend-api-doc-dev/oauth_consent.png" alt="Consent"/>

Here the user will need to approve for the app to access particular resources on behalf of her/him. Continuing the flow brings the user to the next step.

### 2. Accepting user authorization

Do you remember the `Authorization callback URL` specified during app submission? The user will now be redirected to that URL, and you are responsible for taking care of the auth code provided in the query parameters.\
E.g., of the callback:

```http
http://localhost:6000/?code=6O-KEB2KNCWKT7YVFYTF9G&state=adxcsasdcqws
```

You must parse the `code` and proceed to the next step.

### 3. Getting an access token

With the `code` from the previous step you need to generate a POST request to exchange the `code` to an access token.

| Body parameters | Description                          |
| --------------- | ------------------------------------ |
| `code`          | The `code` parsed from the URL       |
| `grant_type`    | Always must be `authorization_code`  |
| `client_id`     | Your OAuth client id                 |
| `client_secret` | Your OAuth client secret             |
| `redirect_uri`  | Same redirect URI used in the step 2 |

E.g.:

```http
POST https://app.omnisend.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=REDIRECT_URI
```

You will get a similar response:

```json
{
  "access_token": "RANDOMLY_GENERATED_ACCESS_TOKEN",
  "expires_in": 9223372036,
  "refresh_token": "RANDOMLY_GENERATED_REFRESH_TOKEN",
  "scope": "RESOURCEX RESOURCEY",
  "token_type": "Bearer"
}
```

That's it! You now have an access token for requested resources for the particular user. Keep it as long as you need, because it will never expire (unless the user decides to revoke it).

## Making a request to the API

With an access token you can start calling our API and interact with resources (such as Contacts, Events, etc).

Here is a sample request to get a contact by provided email:

```http
GET https://api.omnisend.com/api/segments
Content-Type: application/json
Authorization: Bearer RANDOMLY_GENERATED_ACCESS_TOKEN
Omnisend-Version: 2026-03-15
```

***

P.S. If you have any feedback, or you are missing some important information, please contact us via <integrations@omnisend.com>.