API Documentation

TradeVulcan API reference.

TradeVulcan API documentation for OAuth 2.0 client credentials, scoped bearer tokens, contacts, leads, and workspace identity endpoints.

Create API client Developer overview

1. Create credentials

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, short-lived, and revocable.

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 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.

Request body

FieldTypeDescription

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.

Response fields

FieldTypeDescription

access_tokenstringOpaque bearer token prefixed with tvat_.

token_typestringAlways Bearer.

expires_innumberSeconds until expiration. Current lifetime is 3600 seconds.

scopestringGranted 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": 3600,
  "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.

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.

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"