OAuth Providers

The /oauth-providers endpoint manages project-level outbound OAuth 2.0 provider configurations. OAuth Providers store the client credentials and endpoint URLs Vertesia uses to authenticate against third-party services such as Salesforce, HubSpot, GitHub, or custom MCP-backed providers.

Once configured, OAuth Providers can be used by:

• MCP tool collections — reference an OAuth Provider 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

OAuthProvider Object

OAuthProviderAuthStatus Object

List OAuth Providers

Endpoint: /oauth-providers

Method: GET

Requirements: User must have project_settings_write permission.

Headers

Example Response

[
  {
    "id": "6650a1b2c3d4e5f678901234",
    "name": "salesforce",
    "display_name": "Salesforce",
    "project": "6650a1b2c3d4e5f678905678",
    "grant_type": "authorization_code",
    "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

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

Retrieve an OAuth Provider

Endpoint: /oauth-providers/<OAUTH_PROVIDER_ID>

Method: GET

Requirements: User must have project_settings_write permission.

Headers

Path Parameters

Code Example

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

Create an OAuth Provider

Endpoint: /oauth-providers

Method: POST

Requirements: User must have project_settings_write permission.

Headers

Input Parameters

Example Request

{
  "name": "salesforce",
  "display_name": "Salesforce",
  "grant_type": "authorization_code",
  "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

curl --location --request POST 'https://api.vertesia.io/api/v1/oauth-providers' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "salesforce",
  "display_name": "Salesforce",
  "grant_type": "authorization_code",
  "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 Provider

Endpoint: /oauth-providers/<OAUTH_PROVIDER_ID>

Method: PUT

Requirements: User must have project_settings_write permission.

Headers

Path Parameters

Input Parameters

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

Code Example

curl --location --request PUT 'https://api.vertesia.io/api/v1/oauth-providers/<OAUTH_PROVIDER_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 Provider

Endpoint: /oauth-providers/<OAUTH_PROVIDER_ID>

Method: DELETE

Requirements: User must have project_admin permission.

Headers

Path Parameters

Code Example

curl --location --request DELETE 'https://api.vertesia.io/api/v1/oauth-providers/<OAUTH_PROVIDER_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-providers/<OAUTH_PROVIDER_ID>/authorize

Method: GET

Requirements: User must be authenticated.

Headers

Path Parameters

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

curl --location --request GET 'https://api.vertesia.io/api/v1/oauth-providers/<OAUTH_PROVIDER_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-providers/exchange

Method: POST

Requirements: User must be authenticated.

Headers

Input Parameters

Example Response

{
  "success": true
}

Code Example

curl --location --request POST 'https://api.vertesia.io/api/v1/oauth-providers/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 principal has valid OAuth tokens for a provider.

Endpoint: /oauth-providers/<OAUTH_PROVIDER_ID>/status

Method: GET

Requirements: User must be authenticated.

Headers

Path Parameters

Example Response

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

Code Example

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

Connect Client Credentials Provider

Tests and establishes a client_credentials connection by fetching and caching a project-scoped token.

Endpoint: /oauth-providers/<OAUTH_PROVIDER_ID>/connect

Method: POST

Requirements: User must have project_settings_write permission.

Headers

Path Parameters

Example Response

{
  "success": true
}

Code Example

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

Get Access Token

Retrieve a valid access token for an OAuth provider. Automatically refreshes expired tokens when a refresh token is available. Primarily used by workflows and service-side integrations.

Endpoint: /oauth-providers/<OAUTH_PROVIDER_ID>/token

Method: POST

Requirements: User must be authenticated.

Headers

Path Parameters

Example Response

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

Code Example

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

Disconnect

Delete the current principal's stored tokens for an OAuth provider. For client_credentials providers, this deletes the project-scoped cached token. For authorization_code providers, it deletes the current user's token.

Endpoint: /oauth-providers/<OAUTH_PROVIDER_ID>/disconnect

Method: DELETE

Requirements: User must be authenticated.

Headers

Path Parameters

Example Response

{
  "success": true
}

Code Example

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