API Documentation

TradeVulcan API reference.

TradeVulcan API documentation for approved server-to-server access with OAuth 2.0 client credentials, scoped bearer tokens, contacts, leads, and workspace identity endpoints. API use should be tied to a real workspace, approved scopes, and a specific partner or automation workflow.

Request API access Developer overview

1. Create credentials

Approved members with settings access can create a named API client in Workspace Settings, choose scopes, and copy the one-time secret.

2. Request a token

Use HTTP Basic auth or body credentials with grant_type=client_credentials. Tokens are opaque, revocable, and suitable for server-side automation flows.

3. Call v1 endpoints

Send Authorization: Bearer with each API request. Every endpoint enforces the required scope before returning workspace data.

POST

Client credentials

Create access token

/api/oauth/token

Exchanges a workspace API client ID and client secret for a revocable bearer token.

Authentication

HTTP Basic client authentication or body client_id/client_secret

Content type

application/x-www-form-urlencoded or application/json

Use case

Call this from a trusted backend before calling /api/v1 endpoints. Do not call it from browser-only code because it requires the client secret.

Request body

Field	Type	Description
`grant_type`	`string`	Required.Must be client_credentials.
`scope`	`space-delimited string`	Optional subset of scopes already allowed on the API client.
`client_id`	`string`	Required only when not using HTTP Basic auth.
`client_secret`	`string`	Required only when not using HTTP Basic auth.

Response fields

Field	Type	Description
`access_token`	`string`	Opaque bearer token prefixed with tvat_.
`token_type`	`string`	Always Bearer.
`expires_in`	`number`	Seconds until expiration. Current lifetime is 31536000 seconds (365 days).
`scope`	`string`	Granted scopes on this token.

Status codes

200Token issued.

400Unsupported grant type, invalid scope, or malformed request.

401Client credentials are missing, inactive, revoked, or invalid.

500Authorization server could not process the request.

Example request

curl -X POST https://tradevulcan.com/api/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "scope=contacts:read leads:read apps:read"

Example response

{
  "access_token": "tvat_...",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "scope": "contacts:read leads:read apps:read"
}

Pagination

List endpoints accept limit up to 100 and return pagination.nextCursor when more records are available. Pass cursor on the next request.

Revocation

Rotate a client secret from Workspace Settings to revoke existing tokens for that client. Revoke unused clients when a partner connection is retired.

Endpoints

Scopes

contacts:read

List CRM contacts synced or created inside the workspace.

contacts:write

Create contacts for partner-powered workflows.

leads:read

List leads captured by TradeVulcan apps and forms.

leads:write

Create leads from partner systems and external forms.

apps:read

Read the connected workspace and API client profile.

Error shape

OAuth endpoints return error and error_description. v1 endpoints return ok false, error, and message.

Standards note: the first TradeVulcan partner flow follows the OAuth 2.0 client credentials pattern from RFC 6749. Authorization-code plus PKCE for user-delegated apps is future-facing and should not be treated as a public SDK commitment.