OAuth 2.0 Authentication for Yespo API

Use OAuth 2.0 when your server-side app needs to access the Yespo API on behalf of a Yespo user without storing the user's credentials or using a static API key.

OAuth 2.0 lets a user grant your app access to specific Yespo API resources. The app receives tokens and uses them to call Yespo API according to the selected access scopes.

Quick Start

1. Register an OAuth app.
2. Get your Client ID and Client Secret.
3. Build the authorization URL and redirect the user.
4. Exchange the authorization code for tokens.
5. Call the API with the access token.
6. Refresh tokens when needed.
7. Check token status when needed.

How OAuth 2.0 Works

OAuth 2.0 allows a third-party app to access Yespo API on behalf of a Yespo user without receiving the user's login or password.

Example flow:

1. A user connects your app to their Yespo account.
2. Yespo shows an authorization form.
3. The user logs in and grants access.
4. Yespo redirects the user back to your app with an authorization code.
5. Your app exchanges this code for an access token and a refresh token.
6. Your app uses the access token to call Yespo API.

Note: The implementation is supported only for apps with a server part, using response_type=code.

Access Scopes

Access to Yespo API resources is determined by the access scopes selected during app registration.

Choose only the scopes your app actually needs. Scopes limit what your access token can do.

Note: If you change the access scope after registration, already issued tokens continue to work with the old set of permissions. To get a token with updated permissions, the user must go through authorization again.

Register an OAuth App

Before you start integrating with OAuth 2.0, register your app in Yespo.

1. Click the account menu in the upper-right corner and open For partners.

2. On the Partner apps page, click Register app.

3. Provide app information:

   • Name
   • Callback URL — the URL where Yespo redirects the user after they approve or deny authorization (you can leave this blank and add it later)
   • Access scopes — select from the table above

4. Click Register.

After registration, Yespo generates a Client ID and Client Secret for your app. Save them and store them securely — you will need them to request tokens.

Customize the Authorization Form

You can customize how your app appears on the Yespo authorization form. This helps users recognize your app before granting access.

1. Click the account menu in the upper-right corner and open For partners.
2. Find your OAuth app on the Partner apps page.
3. Click Edit.

4. Go to the Authorization form tab.
5. Update the form details:
   • App name — change it if needed
   • Logo — upload your app logo
6. Click Save.

Logo requirements:

• Supported formats: JPG, GIF, PNG
• Maximum file size: 1 MB
• Recommended aspect ratio: 1:1
• Recommended size: 96 × 96 px
• Larger images are cropped to 100% width and center-aligned

Manage an OAuth App

After registration, the app appears on the Partner apps page.

From there, you can:

• copy the Client ID and Client Secret
• edit app settings
• customize the authorization form
• preview the authorization form
• delete the app

Warning: Once an OAuth app is deleted, all related keys, tokens, and integrations become invalid. Any integration using this app will stop working and must be reconfigured with a new OAuth app.

Authorization Flow

Step 1 — Build the Authorization URL

Redirect the user to:

https://uaa.yespo.io/uaa/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL

Parameters:

Step 2 — User Authorization

The user logs in to Yespo and grants access to your app.

After successful authorization, Yespo redirects to the Callback URL with an authorization code:

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?code=YOUR_CODE

Save the code value — you will use it in the next step.

Step 3 — Obtain Tokens

Send a POST request to https://uaa.yespo.io/uaa/oauth/token.

Pass the following parameters in the request body:

Pass parameters in the request body with Content-Type: application/x-www-form-urlencoded. Passing parameters as query string is also supported for backward compatibility but is not recommended.

Authentication — Basic Auth: username is your Client ID, password is your Client Secret.

Response:

{
  "access_token": "OvVWMW5Lh-GLCyASZXrEYtoIkUHQveP-fvtR5oYb41cY9LFlpGMjiQjNllxGUxZf6x4IW3MH_-7u4bOLPFEKPx7wIK35PXYjPVsaAWdhPByqeSRPYcU5gVTYJ0BvB7qV",
  "token_type": "Bearer",
  "refresh_token": "HLrduDsdL0BkJx1BkcDM_W_-ONoukTX7vToccDgagW-An9CLxORnVSdCtQ3l9I8NwhEquJXKSSxDqPfE4puMETI2-e0Npijn1Ve5GXklbu-2bXh6zoe296CqFtXf88yu",
  "scope": "role.full.api.methods",
  "expires_in": 172799
}

Token lifetimes:

• Access token: 48 hours
• Refresh token: 30 days

Both countdowns start from the moment the token is issued.

Step 4 — Call Yespo API

Pass the access token in the Authorization header of every API request:

Authorization: Bearer YOUR_ACCESS_TOKEN

The available API methods depend on the access scope configured during app registration.

Step 5 — Refresh the Access Token

When the access token expires, use the refresh token to get a new pair of tokens without requiring the user to log in again.

Send a POST request to https://uaa.yespo.io/uaa/oauth/token.

Pass the following parameters in the request body:

Pass parameters in the request body with Content-Type: application/x-www-form-urlencoded. Passing parameters as query string is also supported for backward compatibility but is not recommended.

Authentication — Basic Auth: username is your Client ID, password is your Client Secret.

Response:

{
  "access_token": "OvVWMW5Lh-GLCyASZXrEYtoIkUHQveP-fvtR5oYb41cY9LFlpGMjiQjNllxGUxZf6x4IW3MH_-7u4bOLPFEKPx7wIK35PXYjPVsaAWdhPByqeSRPYcU5gVTYJ0BvB7qV",
  "token_type": "Bearer",
  "refresh_token": "HLrduDsdL0BkJx1BkcDM_W_-ONoukTX7vToccDgagW-An9CLxORnVSdCtQ3l9I8NwhEquJXKSSxDqPfE4puMETI2-e0Npijn1Ve5GXklbu-2bXh6zoe296CqFtXf88yu",
  "scope": "role.full.api.methods",
  "expires_in": 172799
}

After a successful refresh, the previous access token becomes invalid — only the new one can be used. Use the new refresh token for subsequent refresh requests.

Token Introspection

To check token status — whether it is active, when it expires, and what scopes it has — send a POST request to https://uaa.yespo.io/uaa/oauth/introspect.

Pass a single parameter in the request body with Content-Type: application/x-www-form-urlencoded:

Authentication — Basic Auth: username is your Client ID, password is your Client Secret.

The response contains token metadata: active status, expiration time, granted scopes, and other details.

The legacy endpoint /oauth/check_token remains available for backward compatibility.

Code Examples

Python

import requests, json

authorize_url = "https://uaa.yespo.io/uaa/oauth/authorize"
token_url = "https://uaa.yespo.io/uaa/oauth/token"
callback_uri = "http://my_host:8081/test/callback"
protected_api_contacts = "https://yespo.io/api/v1/contacts"

client_id = 'YOUR_CLIENT_ID'
client_secret = 'YOUR_CLIENT_SECRET'

authorization_redirect_url = authorize_url + '?response_type=code&client_id=' + client_id + '&redirect_uri=' + callback_uri
print("go to the following url on the browser and enter the code from the returned url: ")
print("---  " + authorization_redirect_url + "  ---")
authorization_code = input('code: ')

data = {'grant_type': 'authorization_code', 'code': authorization_code, 'redirect_uri': callback_uri}
access_token_response = requests.post(token_url, data=data, allow_redirects=False, auth=(client_id, client_secret))

tokens = json.loads(access_token_response.text)
access_token = tokens['access_token']
print("access token: " + access_token)

api_call_headers = {'Authorization': 'Bearer ' + access_token}
api_call_response = requests.get(protected_api_contacts, headers=api_call_headers)
print(api_call_response.text)

Connected Apps

To view apps that have been granted access to your account, click the account menu in the upper-right corner, open Settings, and go to Connected apps.

To disconnect an app, click the three-dot menu next to it and select the appropriate option.

Related

• Getting Started With API
• Connecting to HTTP Request as an External Data Source