Authentication

All BlueSuite API requests require authentication using an API key. This guide explains how to create and use API keys.

API Key Format

BlueSuite API keys use the following format:

wk_<workspace_hash>.<secret_key>

wk_ - Prefix indicating a workspace key
<workspace_hash> - 8-character hash identifying your workspace
<secret_key> - 64-character random secret

Example: wk_a1b2c3d4.e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2g3h4

Creating API Keys

Log in to your BlueSuite dashboard
Navigate to Settings > Integrations
Click Create API Key
Choose a key type based on your use case:
- Embed Forms - For embedding forms on your website
- Zapier - For Zapier integrations
- REST API - For REST API v1 integrations
- General - For custom integrations
Copy and securely store your API key (it won't be shown again)

Each API key is automatically associated with the user who created it. This user is shown as the Owner in the API keys table and is used as the acting user for all write operations (e.g., created_by on new records).

Using API Keys

Include your API key in the Authorization header with a Bearer prefix:

curl -X GET https://app.bluesuite.com/api/v1/contacts \
  -H "Authorization: Bearer wk_a1b2c3d4.your_secret_key"

JavaScript Example

const response = await fetch('https://app.bluesuite.com/api/v1/contacts', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

Python Example

import requests

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://app.bluesuite.com/api/v1/contacts',
    headers=headers
)

data = response.json()

Scopes

API keys have scopes that limit what actions they can perform:

Scope	Description
`contacts:read`	List and retrieve contacts
`contacts:write`	Create, update, and delete contacts
`requests:read`	List and retrieve requests
`requests:write`	Create, update, and delete requests
`quotes:read`	List and retrieve quotes
`quotes:write`	Create, update, and delete quotes
`jobs:read`	List and retrieve jobs
`jobs:write`	Create, update, and delete jobs
`invoices:read`	List and retrieve invoices
`invoices:write`	Create, update, and delete invoices
`events:read`	List and retrieve events
`events:write`	Create, update, and delete events
`timesheets:read`	List and retrieve timesheets and time entries
`timesheets:write`	Create, update, and delete time entries
`properties:read`	List and retrieve contact properties
`properties:write`	Create, update, and delete contact properties
`webhooks:read`	List webhook subscriptions
`webhooks:write`	Create/delete webhook subscriptions
`forms:read`	Read form configurations
`forms:write`	Submit form data
`custom_fields:read`	Read custom field definitions

Key Type Scopes

Different key types have different default scopes:

Key Type	Scopes
Embed Forms	`forms:read`, `forms:write`, `webhooks:read`
Zapier	`forms:read`, `forms:write`, `webhooks:read`, `webhooks:write`
WordPress	`custom_fields:read`, `forms:read`, `forms:write`
REST API	Custom scopes configured at creation time (e.g., `contacts:read`, `quotes:write`)
General	`read`, `write`

Wildcard scopes: General keys with read or write scopes act as wildcards. A key with the read scope grants access to all :read scopes (e.g., contacts:read, quotes:read, etc.). Likewise, write grants all :write scopes.

Security Best Practices

Keep keys secret - Never expose API keys in client-side code or public repositories
Use appropriate scopes - Choose the key type with the minimum required permissions
Rotate keys regularly - Revoke and recreate keys periodically
Monitor usage - Check the "Last Used" timestamp in Settings > Integrations
Revoke compromised keys - If a key is exposed, revoke it immediately

Error Responses

Invalid API Key

{
  "success": false,
  "error": "Invalid API key"
}

HTTP Status: 401 Unauthorized

Missing Scope

{
  "success": false,
  "error": "Insufficient permissions. Required scope: webhooks:write"
}

HTTP Status: 403 Forbidden

Missing User Association

{
  "success": false,
  "error": "API key must be associated with a user. Please recreate the key."
}

HTTP Status: 403 Forbidden

This occurs with API keys created before user association was introduced. Revoke the old key and create a new one to resolve this.

Rate Limited

{
  "success": false,
  "error": "Rate limit exceeded. Try again later."
}

HTTP Status: 429 Too Many Requests

Legacy API Keys

If you have API keys without the wk_ prefix (legacy format), they will continue to work but require passing a workspace_id parameter. We recommend migrating to the new format for better security.

# Legacy format (deprecated)
curl -X GET "https://app.bluesuite.com/api/webhooks/list?workspace_id=123" \
  -H "Authorization: Bearer old_key_format"

# New format (recommended)
curl -X GET https://app.bluesuite.com/api/v1/contacts \
  -H "Authorization: Bearer wk_a1b2c3d4.your_secret_key"

On this page