Authorization

The WebWork Time Tracker 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 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.

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

1. Log in to your WebWork account
2. Navigate to Settings > REST API > OAuth2 Apps
3. Click "Create App"
4. Enter your application name (e.g., "My Integration App")
5. Provide your redirect URI (where users will be redirected after authorization)
   • Example: https://myapp.com/callback
   • Must match exactly when making authorization requests
6. Select the grant type:
   • Authorization Code Grant - For web applications with user authorization
   • Client Credentials Grant - For server-to-server authentication
7. Click "Create"
8. 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

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://app.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..."
}

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

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

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.

• 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

Scopes define what your token is allowed to do, and they are enforced on every request — a valid token with the wrong scope is rejected.

• read - Read access

  • GET requests only
  • Cannot create, change or delete anything

• write - Read and write access

  • POST, PUT, PATCH and DELETE, including deletes
  • Also permits GET, so most integrations need only write

• admin - Everything write allows, plus AI-assistant approval actions

  • Only required for the WebWork AI assistant's approval tools (timesheets, leave requests, time requests)
  • Not needed to delete records over the REST API — write covers that

What each request needs:

If your token is missing the scope, the request fails with 403:

{
  "success": false,
  "message": "Insufficient OAuth scope. This action requires the \"write\" or \"admin\" scope; this token was granted \"read\".",
  "meta": {
    "required_scope": ["write", "admin"],
    "granted_scope": ["read"]
  }
}

meta.required_scope and meta.granted_scope let you detect this case programmatically rather than parsing the message.

How Scopes Work:

• Personal Access Tokens - choose the scopes when you create the token. read and write are selected by default. admin is not offered here; request it through OAuth2 if you need it.
• OAuth2 - request scopes in the authorization URL: scope=read write. If you omit scope entirely, the token is issued with read only, so always request what you need explicitly.
• The authorization screen shows the user exactly which permissions your app is asking for. They approve or deny the whole request — individual scopes cannot be unticked.
• Refreshing a token keeps the same scopes. To change scopes, run the authorization flow again.

Example: Requesting Scopes in OAuth2 Flow

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

• Authorization URL: https://app.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.

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

• Auth URL: https://app.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 provide a simpler authentication method, perfect for:

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

1. Log in to your WebWork account
2. Navigate to Settings > REST API > Personal Access Tokens
3. Click "Create Token"
4. Enter a descriptive name (e.g., "My Integration", "Production API", "Testing Script")
5. Choose the token's scopes. Read and Write are ticked by default, which is what most integrations need. Untick Write for a token that must never change anything. At least one scope is required.
6. Click "Create Token"
7. Important: Copy the token immediately - you won't be able to see it again!

Scopes cannot be changed after creation — create a new token if you need different access.

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

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

• 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

Important: WebWork 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.

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

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

Check the response body — there are two different causes:

• "Insufficient OAuth scope..." - your token lacks the scope for this action. Compare meta.granted_scope with meta.required_scope. A read-only token cannot write; create a new token with write, or re-run the OAuth2 flow requesting scope=read write.
• Anything else - a permissions problem rather than a scope problem:
  • Verify you have the required role (Owner or Executive Manager)
  • Check that you're using the correct workspace_id for workspace-specific endpoints

You've hit either the per-minute limit (150) or the write burst limit (20 writes/second). Read the Retry-After header and wait that many seconds before retrying — 60 means you've exhausted the per-minute allowance, 1 means you're simply sending writes too fast and only need to pace them.

If you're bulk-importing, send writes in a steady stream rather than all at once. Contact api-support@webwork-tracker.com if your integration genuinely needs a higher limit.

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

• 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

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

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