OAuth authentication

Learn how to integrate with the Vend Email API using OAuth 2.0.

Setting up your OAuth app

Before you can begin using the API, you'll need to register your application. Navigate to "Integrations" and click "Add". You'll need to provide:

• Application name
• Redirect URI (where users will be sent after authorization)

Upon creation, you'll receive your client_id and client_secret. Keep these credentials secure and never share them publicly.

Authorization flow

1. Authorization request

Direct your users to visit this URL in their browser:

https://www.vend.email/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=read_user

After they approve the connection, they'll be redirected to your redirect_uri with a code parameter, like:

https://your-app.com/callback?code=AUTHORIZATION_CODE

2. Exchange code for an access token

After authorization, exchange the code for an access token:

curl -X POST https://www.vend.email/oauth/token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=AUTHORIZATION_CODE \
  -d grant_type=authorization_code \
  -d redirect_uri=YOUR_REDIRECT_URI

Response:

{
  "access_token": "vcXTnCUh1POc62pCz6SFJVt7e-V9j341bsLXGfzuq20",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "6MAY8ZjGjLULXRUA7byf3Pk5AqkpT72WSmGQtZdZOEo",
  "scope":"public",
  "created_at":1732828541
}

Using the API

Once you have an access token, you can make authenticated requests to our API endpoints.

Get current user

Retrieve information about the authenticated user:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://www.vend.email/api/v1/me

Response:

{
  "id": "123456",
  "email": "[email protected]"
}

Refreshing access tokens

Access tokens expire after two hours. Use your refresh token to obtain a new access token:

curl -X POST https://www.vend.email/oauth/token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=YOUR_REFRESH_TOKEN \
  -d grant_type=refresh_token

Response:

{
  "access_token": "e9q4UW-Y9v-Opbzk3doxDCcjmyRUdG72eIvi3U3fpIo",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "M0nBULHtAKx6zvAtBVyBZeSmN3d6S5f71dFMA2frkY8",
  "scope":"public",
  "created_at":1732828975
}

Security best practices

• Store your client_secret securely on your backend - never expose it in client-side code or repositories
• Validate the state parameter in OAuth callbacks to prevent CSRF attacks
• Use HTTPS for all OAuth redirect URIs
• Store access tokens securely and encrypt them at rest
• Implement token refresh logic before tokens expire
• Maintain a token revocation system in case of security breaches