Authentication - WallJobs AI Documentation

Authenticate with the WallJobs AI API using JWT tokens or API keys. Learn about OAuth integration.

Overview

WallJobs AI API supports two authentication methods:

- Long-lived keys for server-to-server integrations
-

For most integrations, API keys are the recommended approach. JWT tokens are useful when building applications that need to act on behalf of specific users.

API Keys

API keys provide a simple way to authenticate server-to-server requests. Each key is tied to an organization and can be scoped to specific workspaces and permissions.

Generating API Keys

Go to Settings → API
Click Create API Key
Enter a descriptive name (e.g., "Production Integration")
Select the scopes/permissions for this key
Choose which workspaces this key can access
Click Create
Copy the key immediately - it won't be shown again

Store Securely

The API key is only shown once when created. Store it securely in your environment variables or secrets manager. If lost, you'll need to create a new key.

Using API Keys

Include your API key in the Authorization header with the Bearer scheme:

curl https://api.walljobs.com.br/v1/contacts \
  -H "Authorization: Bearer wj_live_abc123xyz789..."

API keys follow this format:

wj_live_* - Production keys
wj_test_* - Test/sandbox keys (if available)

Key Scopes

API keys can be scoped to limit what actions they can perform:

Scope	Description
`contacts:read`	Read contact data
`contacts:write`	Create and update contacts
`searches:read`	Read search results
`searches:execute`	Execute AI searches
`shortlists:read`	Read shortlists and pipelines
`shortlists:write`	Manage shortlists
`sequences:read`	Read sequence data
`sequences:write`	Create and manage sequences
`webhooks:manage`	Configure webhooks

Principle of Least Privilege

Only grant the scopes your integration actually needs. This limits potential damage if a key is compromised.

JWT Tokens

JWT tokens are used for user-specific access, typically in applications that need to perform actions on behalf of a logged-in user.

To obtain a JWT token:

curl -X POST https://api.walljobs.com.br/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_abc123..."
}

JWT tokens expire after 1 hour. Use the refresh token to obtain new access tokens without requiring user credentials again.

Workspace Context

Most API endpoints require a workspace context. Specify the workspace using the X-Workspace-ID header:

curl https://api.walljobs.com.br/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123"

Get your workspace IDs from the dashboard or by calling the workspaces endpoint:

curl https://api.walljobs.com.br/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"

Note

If your API key is scoped to a single workspace, the X-Workspace-ID header is optional - requests will automatically use that workspace.

Security Best Practices

Follow these practices to keep your API integration secure:

Revoking API Keys

To revoke an API key:

The key is immediately invalidated - any requests using it will receive a 401 error.