OAuth

Private Beta

Currently, we do support the OAuth Authorization Code Grant flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1) standard in v5 endpoints. If you would like to use it please contact us [email protected].

Usage

After contacting us we will provide you with the required parameters to use Oauth. Below you can find information on how to use it.

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.

E.g.:

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.

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://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.:

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:

{
  "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:

GET https://api.omnisend.com/v5/events
Content-Type: application/json
Authorization: Bearer RANDOMLY_GENERATED_ACCESS_TOKEN

P.S. If you have any feedback, or you are missing some important information, please contact us via [email protected].