OAuth Applications

The /oauth-apps endpoint manages project-level OAuth 2.0 application configurations. OAuth Applications store the client credentials and endpoint URLs needed to authenticate users with third-party services (e.g., Salesforce, HubSpot, GitHub).

Once configured, OAuth Applications can be used by:

MCP tool collections — reference an OAuth Application instead of relying on dynamic client registration (see Tool Collections)
Workflow activities — request tokens for OAuth-protected APIs
UI integrations — authenticate users via the standard OAuth 2.0 Authorization Code flow with optional PKCE

OAuthApplication Object

Field	Data Type	Description
id	`string`	Unique identifier for the OAuth application.
name	`string`	Kebab-case identifier, unique within the project.
display_name	`string`	Human-readable label.
project	`string`	Project ID this application belongs to.
authorization_endpoint	`string`	OAuth 2.0 authorization URL.
token_endpoint	`string`	OAuth 2.0 token exchange URL.
client_id	`string`	OAuth client identifier.
has_client_secret	`boolean`	Whether a client secret is configured (never returned in plaintext).
default_scopes	`string[]`	Default OAuth scopes to request during authorization.
use_pkce	`boolean`	Whether PKCE is used for authorization flows.
revocation_endpoint	`string`	OAuth 2.0 token revocation URL.
created_at	`string`	ISO 8601 creation timestamp.
updated_at	`string`	ISO 8601 last update timestamp.

OAuthAppAuthStatus Object

Field	Data Type	Description
oauth_app_id	`string`	The OAuth application ID.
oauth_app_name	`string`	The OAuth application name.
authenticated	`boolean`	Whether the current user has valid tokens.
expires_at	`string`	ISO 8601 token expiration time.
scope	`string`	Granted OAuth scopes.

List OAuth Applications

Endpoint: /oauth-apps

Method: GET

Requirements: User must have project_settings_write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Example Response

[
  {
    "id": "6650a1b2c3d4e5f678901234",
    "name": "salesforce",
    "display_name": "Salesforce",
    "project": "6650a1b2c3d4e5f678905678",
    "authorization_endpoint": "https://login.salesforce.com/services/oauth2/authorize",
    "token_endpoint": "https://login.salesforce.com/services/oauth2/token",
    "client_id": "3MVG9...",
    "has_client_secret": true,
    "default_scopes": ["api", "refresh_token"],
    "use_pkce": true,
    "revocation_endpoint": "https://login.salesforce.com/services/oauth2/revoke",
    "created_at": "2024-06-01T12:00:00.000Z",
    "updated_at": "2024-06-01T12:00:00.000Z"
  }
]

Code Example

List OAuth Applications

curl --location --request GET 'https://api.vertesia.io/api/v1/oauth-apps' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Retrieve an OAuth Application

Endpoint: /oauth-apps/<OAUTH_APP_ID>

Method: GET

Requirements: User must have project_settings_write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<OAUTH_APP_ID>`	`string`	(Required) The ID of the OAuth application.

Code Example

Retrieve OAuth Application

curl --location --request GET 'https://api.vertesia.io/api/v1/oauth-apps/<OAUTH_APP_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Create an OAuth Application

Endpoint: /oauth-apps

Method: POST

Requirements: User must have project_settings_write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
name	`string`	(Required) Kebab-case identifier, unique within the project.
display_name	`string`	(Required) Human-readable label.
authorization_endpoint	`string`	OAuth 2.0 authorization URL. Required for standalone OAuth apps; auto-discovered for MCP OAuth apps.
token_endpoint	`string`	OAuth 2.0 token exchange URL. Required for standalone OAuth apps; auto-discovered for MCP OAuth apps.
client_id	`string`	(Required) OAuth client identifier.
client_secret	`string`	Client secret (encrypted at rest, never returned in responses).
default_scopes	`string[]`	Default OAuth scopes.
use_pkce	`boolean`	Use PKCE for authorization flows. Defaults to `true`.
revocation_endpoint	`string`	OAuth 2.0 token revocation URL.

Example Request

{
  "name": "salesforce",
  "display_name": "Salesforce",
  "authorization_endpoint": "https://login.salesforce.com/services/oauth2/authorize",
  "token_endpoint": "https://login.salesforce.com/services/oauth2/token",
  "client_id": "3MVG9...",
  "client_secret": "my-secret-value",
  "default_scopes": ["api", "refresh_token"],
  "use_pkce": true,
  "revocation_endpoint": "https://login.salesforce.com/services/oauth2/revoke"
}

Code Example

Create OAuth Application

curl --location --request POST 'https://api.vertesia.io/api/v1/oauth-apps' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "salesforce",
  "display_name": "Salesforce",
  "authorization_endpoint": "https://login.salesforce.com/services/oauth2/authorize",
  "token_endpoint": "https://login.salesforce.com/services/oauth2/token",
  "client_id": "3MVG9...",
  "client_secret": "my-secret-value",
  "default_scopes": ["api", "refresh_token"],
  "use_pkce": true
}'

Update an OAuth Application

Endpoint: /oauth-apps/<OAUTH_APP_ID>

Method: PUT

Requirements: User must have project_settings_write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Data Type	Description
`<OAUTH_APP_ID>`	`string`	(Required) The ID of the OAuth application.

Input Parameters

All fields from the create payload are accepted. Only provided fields are updated.

Parameter	Data Type	Description
display_name	`string`	Human-readable label.
authorization_endpoint	`string`	OAuth 2.0 authorization URL.
token_endpoint	`string`	OAuth 2.0 token exchange URL.
client_id	`string`	OAuth client identifier.
client_secret	`string`	New client secret. Send empty string to clear.
default_scopes	`string[]`	Default OAuth scopes.
use_pkce	`boolean`	Use PKCE for authorization flows.
revocation_endpoint	`string`	OAuth 2.0 token revocation URL.

Code Example

Update OAuth Application

curl --location --request PUT 'https://api.vertesia.io/api/v1/oauth-apps/<OAUTH_APP_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "display_name": "Salesforce Production",
  "default_scopes": ["api", "refresh_token", "full"]
}'

Delete an OAuth Application

Endpoint: /oauth-apps/<OAUTH_APP_ID>

Method: DELETE

Requirements: User must have project_admin permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<OAUTH_APP_ID>`	`string`	(Required) The ID of the OAuth application.

Code Example

Delete OAuth Application

curl --location --request DELETE 'https://api.vertesia.io/api/v1/oauth-apps/<OAUTH_APP_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Initiate OAuth Authorization

Starts an OAuth 2.0 Authorization Code flow for the current user. Returns an authorization URL to open in a popup or browser.

Endpoint: /oauth-apps/<OAUTH_APP_ID>/authorize

Method: GET

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<OAUTH_APP_ID>`	`string`	(Required) The ID of the OAuth application.

Example Response

{
  "authorization_url": "https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=3MVG9...&redirect_uri=https%3A%2F%2Fapp.vertesia.io%2Foauth%2Fcallback&state=abc123&code_challenge=xyz&code_challenge_method=S256&scope=api+refresh_token",
  "state": "abc123"
}

Code Example

Initiate Authorization

curl --location --request GET 'https://api.vertesia.io/api/v1/oauth-apps/<OAUTH_APP_ID>/authorize' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Exchange Authorization Code

Called by the UI callback page after the user completes authorization. Exchanges the authorization code for tokens and stores them server-side.

Endpoint: /oauth-apps/exchange

Method: POST

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
code	`string`	(Required) Authorization code from the OAuth provider.
state	`string`	(Required) State parameter for CSRF verification.

Example Response

{
  "success": true
}

Code Example

Exchange Authorization Code

curl --location --request POST 'https://api.vertesia.io/api/v1/oauth-apps/exchange' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "code": "auth_code_from_provider",
  "state": "abc123"
}'

Check Authentication Status

Check whether the current user has valid OAuth tokens for an application.

Endpoint: /oauth-apps/<OAUTH_APP_ID>/status

Method: GET

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<OAUTH_APP_ID>`	`string`	(Required) The ID of the OAuth application.

Example Response

{
  "oauth_app_id": "6650a1b2c3d4e5f678901234",
  "oauth_app_name": "salesforce",
  "authenticated": true,
  "expires_at": "2024-06-01T13:00:00.000Z",
  "scope": "api refresh_token"
}

Code Example

Check Authentication Status

curl --location --request GET 'https://api.vertesia.io/api/v1/oauth-apps/<OAUTH_APP_ID>/status' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Access Token

Retrieve a valid access token for an OAuth application. Automatically refreshes expired tokens when a refresh token is available. Primarily used by workflow activities.

Endpoint: /oauth-apps/<OAUTH_APP_ID>/token

Method: POST

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<OAUTH_APP_ID>`	`string`	(Required) The ID of the OAuth application.

Example Response

{
  "access_token": "eyJhbGciOi..."
}

Code Example

Get Access Token

curl --location --request POST 'https://api.vertesia.io/api/v1/oauth-apps/<OAUTH_APP_ID>/token' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{}'

Disconnect (Revoke Tokens)

Delete the current user's stored tokens for an OAuth application.

Endpoint: /oauth-apps/<OAUTH_APP_ID>/disconnect

Method: DELETE

Requirements: User must be authenticated.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<OAUTH_APP_ID>`	`string`	(Required) The ID of the OAuth application.

Example Response

{
  "success": true
}

Code Example

Disconnect

curl --location --request DELETE 'https://api.vertesia.io/api/v1/oauth-apps/<OAUTH_APP_ID>/disconnect' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'