Getting Started with the Speculo API

Three simple steps to start using the Speculo API:

1. Get your credentials from Speculo

Contact the Speculo team to receive:

• clientId (e.g., client_abc123)
• refreshToken (e.g., rt_live_xxxxxxxxx)
• orgId (your organization identifier)

These credentials are provisioned once and can be reused indefinitely.

2. Exchange your refresh token for an access token

Call this once to get your access token:

curl -X POST https://speculo-api-oauth-54875993561.us-central1.run.app/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client_abc123",
    "refreshToken": "rt_live_xxxxxxxxx"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer"
}

Important: Save this accessToken - it never expires (until you rotate credentials).

3. Use the access token on all API requests

curl -X GET "https://api.speculo.ai/v1/contacts?pageSize=50" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

That's it! Use the same access token for all requests. No refresh logic, no expiry to track.

When to get a new access token

Only get a new access token when:

• You're rotating credentials for security
• You need to revoke the old token

Otherwise, keep using the same token.

Need help?

Contact [email protected] with your organization ID and client ID for assistance with:

• Credential rotation
• Access issues
• Integration questions