Authorization
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Overview

The WebWork Tracker REST API V2 supports two authentication methods: OAuth2 and Personal Access Tokens. Both methods use Bearer token authentication in the HTTP Authorization header.

Choose the authentication method that best fits your use case:

OAuth2 - Best for applications that need user authorization and automatic token refresh
Personal Access Tokens - Best for scripts, testing, or simple integrations

OAuth2 Authentication

OAuth2 authentication uses the Authorization Code flow, which is ideal for applications that need to access user data on their behalf. This method provides secure, user-authorized access with automatic token refresh capabilities.

Getting Started with OAuth2

Step 1: Create an OAuth2 Application

Before you can use OAuth2 authentication, you need to register your application:

Log in to your WebWork account
Navigate to Settings > REST API > OAuth2 Apps
Click "Create App"
Enter your application name (e.g., "My Integration App")
Provide your redirect URI (where users will be redirected after authorization)
- Example: https://myapp.com/callback
- Must match exactly when making authorization requests
Select the grant type:
- Authorization Code Grant - For web applications with user authorization
- Client Credentials Grant - For server-to-server authentication
Click "Create"
Important: Copy your Client ID and Client Secret immediately - you won't be able to see the secret again!

Create OAuth2 App: https://webwork-tracker.com/app/settings/rest-api

Step 2: Authorization Flow

The OAuth2 Authorization Code flow consists of three main steps:

Step 1: Redirect User to Authorization URL

Redirect the user to the authorization URL with your client credentials:

GET https://webwork-tracker.com/oauth/authorize?
    client_id=YOUR_CLIENT_ID&
    redirect_uri=YOUR_REDIRECT_URI&
    response_type=code&
    scope=read write

Parameters:

client_id - Your OAuth2 application's Client ID
redirect_uri - Must match the redirect URI registered with your app
response_type - Always code for Authorization Code flow
scope - Space-separated list of requested scopes (read, write, admin)

Step 2: User Authorizes Your Application

The user will be redirected to WebWork's authorization page. After they approve your application, they'll be redirected back to your redirect_uri with an authorization code:

https://your-redirect-uri.com/callback?code=AUTHORIZATION_CODE

Step 3: Exchange Authorization Code for Tokens

Exchange the authorization code for an access token and refresh token:

POST https://api.webwork-tracker.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI

Response:

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "def50200a1b2c3d4e5f6..."
}

Step 3: Using Access Tokens

Include the access token in all API requests using the Authorization header:

GET https://api.webwork-tracker.com/api/v2/workspaces
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Step 4: Refreshing Access Tokens

Access tokens expire after 15 days. Use the refresh token to obtain a new access token before expiration:

POST https://api.webwork-tracker.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
refresh_token=YOUR_REFRESH_TOKEN

Response:

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "def50200a1b2c3d4e5f6..." // New refresh token
}

Important: Always save the new refresh token - the old one becomes invalid after use.

OAuth2 Token Expiration

Access tokens: Expire after 15 days
Refresh tokens: Expire after 30 days
Always refresh your access token before it expires to maintain uninterrupted API access

OAuth2 Scopes

Scopes define what permissions your application has. When creating an OAuth2 application or Personal Access Token, you can specify which scopes the token should have:

read - Read access to resources (projects, tasks, reports, members, workspaces)
- Allows GET requests to retrieve data
- Required for viewing workspace information, members, projects, tasks, etc.
write - Write access to create and update resources
- Allows POST and PUT requests to create and modify data
- Required for creating projects, tasks, members, updating resources, etc.
admin - Administrative access to all resources
- Full access including DELETE operations
- Required for deleting resources, managing workspace settings, etc.

How Scopes Work:

When creating a Personal Access Token, you can specify scopes in the scopes array
When using OAuth2 Authorization Code flow, request scopes in the authorization URL: scope=read write
Users can approve or deny specific scopes during authorization
Tokens store their granted scopes, which can be checked programmatically

Example: Requesting Scopes in OAuth2 Flow

GET https://webwork-tracker.com/oauth/authorize?
    client_id=YOUR_CLIENT_ID&
    redirect_uri=https://your-app.com/callback&
    response_type=code&
    scope=read write

OAuth2 Endpoints

Authorization URL: https://webwork-tracker.com/oauth/authorize
Token URL: https://api.webwork-tracker.com/oauth/token

The token URL is used for both obtaining new tokens and refreshing expired tokens.

OAuth2 Configuration Values

When configuring OAuth2 in your application or API client (like Postman), use these values:

Auth URL: https://webwork-tracker.com/oauth/authorize
Access Token URL: https://api.webwork-tracker.com/oauth/token
Client ID: Your OAuth2 App Client ID (from Settings > REST API)
Client Secret: Your OAuth2 App Client Secret (from Settings > REST API)
Scope: read write (or admin)
State: (optional - leave empty or use random string)
Client Authentication: Send as Basic Auth header
Redirect URI: Must match exactly the redirect URI you registered when creating the OAuth2 app (e.g., https://your-app.com/callback)

Personal Access Tokens

Personal Access Tokens provide a simpler authentication method, perfect for:

Scripts and automation
Testing and development
Applications that don't need user authorization flows
Long-running integrations

Getting Started with Personal Access Tokens

Step 1: Create a Personal Access Token

Log in to your WebWork account
Navigate to Settings > REST API > Personal Access Tokens
Click "Create Token"
Enter a descriptive name (e.g., "My Integration", "Production API", "Testing Script")
Click "Create Token"
Important: Copy the token immediately - you won't be able to see it again!

Create Personal Access Token: https://webwork-tracker.com/app/settings/rest-api

Step 2: Using Personal Access Tokens

Include the token in all API requests using the Authorization header:

GET https://api.webwork-tracker.com/api/v2/workspaces
Authorization: Bearer your-personal-access-token-here

Personal Access Token Management

View Tokens: See all your active tokens in Settings > REST API
Token Expiration: Tokens expire after 6 months
Revoke Tokens: Archive (revoke) tokens anytime if they're compromised
No Refresh: Personal Access Tokens don't support refresh - create a new token when one expires

Personal Access Token vs OAuth2

Feature	Personal Access Tokens	OAuth2
Setup Complexity	Simple (one step)	More complex (app registration + flow)
User Authorization	Not required	Required
Token Expiration	6 months	15 days (access), 30 days (refresh)
Token Refresh	No (create new token)	Yes (automatic refresh)
Best For	Scripts, testing, simple integrations	Production applications, user-facing apps

Access Requirements

Important: REST API V2 access is restricted to:

Workspace Owners
Executive Managers

Only users with these roles can:

Create OAuth2 applications
Generate Personal Access Tokens
Make API requests

If you don't have the required role, contact your workspace owner or administrator to request access.

Security Best Practices

Never commit tokens to version control - Use environment variables or secure secret management
Rotate tokens regularly - Create new tokens periodically and revoke old ones
Use HTTPS only - Always use HTTPS in production
Store tokens securely - Use secure storage mechanisms appropriate for your platform
Monitor token usage - Regularly review active tokens and revoke unused or compromised ones
Use appropriate scopes - Request only the minimum scopes needed for your application

Troubleshooting

"Unauthorized" Error (401)

Check that your token is correctly included in the Authorization header
Verify the token hasn't expired
Ensure you're using the correct token format: Authorization: Bearer <token>

"Forbidden" Error (403)

Verify you have the required role (Owner or Executive Manager)
Check that you're using the correct workspace_id for workspace-specific endpoints

Token Expired

OAuth2: Use the refresh token to obtain a new access token
Personal Access Token: Create a new token in Settings > REST API

Invalid Redirect URI

Ensure the redirect URI in your authorization request exactly matches the one registered with your OAuth2 app
Check for trailing slashes, HTTP vs HTTPS, and exact path matching

Verifying Authentication

Check if Your Token is Valid

Test your authentication with a simple API call:

# Test with OAuth2 or Personal Access Token
curl -X GET "https://api.webwork-tracker.com/api/v2/workspaces" \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200):

{
  "success": true,
  "data": [...],
  "meta": {...}
}

Authentication Error (401):

{
  "success": false,
  "message": "Unauthorized. Please provide a valid Bearer token or Basic Auth credentials."
}

Need Help?

API Support: api-support@webwork-tracker.com
Settings Page: https://webwork-tracker.com/app/settings/rest-api

AuthorizationCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code