Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt

Use this file to discover all available pages before exploring further.

Rotating your app issues a new client_secret and immediately invalidates the previous one. This is the only way to update your app’s name, description, avatar, redirect URIs, or scopes.
If you change the scopes during rotation, all active user sessions will be revoked. Users will need to go through the OAuth flow again to approve the new scopes. If you keep the same scopes, existing sessions are preserved.

​
When to rotate

  • You need to change the app name, description, or avatar
  • You need to add or remove redirect URIs
  • You need to request different scopes
  • Your client_secret was compromised or lost

​
How it works

Rotation is not an update. It is a re-registration using your client_id as proof of ownership. The new credentials are always sent to the email address registered with the app. That email cannot be changed.
1

Submit the rotation request

Call POST /v1/auth/rotate-app with your current client_id and the new values you want.
2

Receive new credentials by email

A new client_secret is generated and sent to the email address registered with the app. The old secret is invalidated immediately.
3

Update your app

Replace the stored client_secret in your app with the new value.
4

Users re-authorize (only if scopes changed)

If you changed the scopes, existing tokens are revoked and users must re-authorize. If the scopes are unchanged, active sessions continue working normally.

​
Rotate via API

Send a POST to /v1/auth/rotate-app: 
curl -X POST https://api.vendaze.com/v1/auth/rotate-app \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "app_name": "My Integration v2",
    "description": "Updated description for My Integration",
    "avatar_url": "https://yourapp.com/assets/vendaze-avatar-v2.webp",
    "redirect_uris": ["https://yourapp.com/oauth/callback"],
    "scopes": ["people:read", "people:write", "deals:read", "deals:write"]
  }'
Response (201): 
{
  "data": {
    "app_name": "My Integration v2",
    "client_id": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "message": "New credentials sent to dev@yourapp.com"
  }
}
The new client_secret is sent only by email to the address registered with the app and never returned in the API response. Store it securely as soon as you receive it.

​
Request parameters

ParameterTypeRequiredDescription
client_idstringYesCurrent client_id of the app being rotated.
app_namestringYesNew name shown to users on the consent screen. Max 100 chars.
descriptionstringNoNew description of what your app does. Max 500 chars.
avatar_urlstringNoHTTPS URL of a WebP image shown on the consent screen. Max 400x400 px.
redirect_urisstring[]YesNew list of HTTPS redirect URIs. Replaces the previous list entirely.
scopesstring[]YesNew list of scopes. Replaces the previous list entirely.
The registered email address cannot be changed. New credentials are always sent to the original email used during registration.

​
What changes after rotation

FieldAfter rotation
client_secretNew value. Sent by email. Update your app.
Active user tokensRevoked only if scopes changed. Unchanged scopes keep sessions active.
App nameUpdated to the value in the request.
Redirect URIsReplaced by the list in the request.
ScopesReplaced by the list in the request.

​
Impact on your users

If you change the scopes, all access tokens and refresh tokens are immediately revoked. The next time a user’s app makes an API call, it will receive a 401 Unauthorized. Your app should handle this by redirecting the user through the OAuth flow again. If you keep the same scopes, active sessions are not affected. Users will not notice the rotation.

Register your app

First-time registration to get your initial credentials.

Authentication

Implement the OAuth 2.1 flow after updating your credentials.