TradeVulcan API documentation for OAuth 2.0 client credentials, scoped bearer tokens, contacts, leads, and workspace identity endpoints.
Members with settings access can create a named API client in Workspace Settings, choose scopes, and copy the one-time secret.
Use HTTP Basic auth or body credentials with grant_type=client_credentials. Tokens are opaque, short-lived, and revocable.
Send Authorization: Bearer with each API request. Every endpoint enforces the required scope before returning workspace data.
/api/oauth/tokenExchanges a workspace API client ID and client secret for a short-lived 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.
grant_typestringRequired.Must be client_credentials.scopespace-delimited stringOptional subset of scopes already allowed on the API client.client_idstringRequired only when not using HTTP Basic auth.client_secretstringRequired only when not using HTTP Basic auth.access_tokenstringOpaque bearer token prefixed with tvat_.token_typestringAlways Bearer.expires_innumberSeconds until expiration. Current lifetime is 3600 seconds.scopestringGranted scopes on this token.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.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"{
"access_token": "tvat_...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "contacts:read leads:read apps:read"
}List endpoints accept limit up to 100 and return pagination.nextCursor when more records are available. Pass cursor on the next request.
Rotate a client secret from Workspace Settings to revoke existing tokens for that client. Revoke unused clients when a partner connection is retired.
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 planned on top of the same API client model.
AI-first growth apps for home-service teams: proof, follow-up, local presence, lead capture, and customer context.
Markets