Authentication

API Authentication

Global Watch API supports multiple authentication methods to suit different use cases. This guide covers how to authenticate your API requests securely.

Authentication Methods

Method	Use Case	Security Level
API Keys	Server-to-server integrations	High
OAuth 2.0	User-authorized applications	High
Service Tokens	Automated workflows	High

API Keys

API keys are the simplest way to authenticate with the Global Watch API. They're ideal for server-side applications and scripts.

Generating an API Key

Log in to your Global Watch account
Navigate to Settings → API Keys
Click Generate New Key
Provide a descriptive name for the key
Select the appropriate permissions
Click Create Key

Your API key will only be shown once. Copy it immediately and store it securely.

Using API Keys

Include your API key in the Authorization header:

curl -X GET "https://api.global.watch/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Key Permissions

When creating an API key, you can scope its permissions:

Permission	Description
`projects:read`	Read project data
`projects:write`	Create and update projects
`assets:read`	Read asset data
`assets:write`	Create and update assets
`members:read`	Read team member data
`members:write`	Manage team members
`billing:read`	Read billing information
`admin`	Full administrative access

API Key Best Practices

Follow these best practices to keep your API keys secure.

Never expose keys in client-side code - API keys should only be used server-side
Use environment variables - Store keys in environment variables, not in code
Rotate keys regularly - Generate new keys periodically and revoke old ones
Use minimal permissions - Only grant the permissions your application needs
Monitor usage - Review API key activity in your dashboard

// ✅ Good - Using environment variables
const apiKey = process.env.GLOBALWATCH_API_KEY;

// ❌ Bad - Hardcoded key
const apiKey = 'fw_live_abc123...';

Revoking API Keys

To revoke an API key:

Go to Settings → API Keys
Find the key you want to revoke
Click the Revoke button
Confirm the action

Revoking a key is immediate and irreversible. Any applications using the key will stop working.

OAuth 2.0

OAuth 2.0 is recommended for applications that act on behalf of users. It provides secure, scoped access without exposing user credentials.

OAuth Flow Overview

┌──────────┐                              ┌──────────────┐
│   User   │                              │  Global Watch │
└────┬─────┘                              └──────┬───────┘
     │                                           │
     │  1. User clicks "Connect Global Watch"     │
     │ ─────────────────────────────────────────>│
     │                                           │
     │  2. Redirect to authorization page        │
     │ <─────────────────────────────────────────│
     │                                           │
     │  3. User grants permission                │
     │ ─────────────────────────────────────────>│
     │                                           │
     │  4. Redirect with authorization code      │
     │ <─────────────────────────────────────────│
     │                                           │
     │  5. Exchange code for access token        │
     │ ─────────────────────────────────────────>│
     │                                           │
     │  6. Return access token                   │
     │ <─────────────────────────────────────────│

Setting Up OAuth

1. Register Your Application

Go to Settings → Developer → OAuth Applications
Click Create Application
Fill in the application details:
- Name: Your application name
- Redirect URIs: Authorized callback URLs
- Scopes: Required permissions
Save your Client ID and Client Secret

2. Authorization Request

Redirect users to the authorization endpoint:

https://global.watch/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=projects:read assets:read&
  state=random_state_string

Parameter	Description	Required
`client_id`	Your OAuth application client ID	Yes
`redirect_uri`	URL to redirect after authorization	Yes
`response_type`	Must be `code`	Yes
`scope`	Space-separated list of permissions	Yes
`state`	Random string for CSRF protection	Recommended

3. Handle the Callback

After the user authorizes, they're redirected to your callback URL:

https://yourapp.com/callback?code=AUTH_CODE&state=random_state_string

4. Exchange Code for Token

Exchange the authorization code for an access token:

curl -X POST "https://api.global.watch/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback"

Response:

{
  "access_token": "fw_oauth_abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "fw_refresh_xyz789...",
  "scope": "projects:read assets:read"
}

5. Use the Access Token

Include the access token in API requests:

curl -X GET "https://api.global.watch/v1/projects" \
  -H "Authorization: Bearer fw_oauth_abc123..."

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get a new access token:

curl -X POST "https://api.global.watch/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=fw_refresh_xyz789..."

OAuth Scopes

Scope	Description
`profile`	Read user profile information
`projects:read`	Read project data
`projects:write`	Create and modify projects
`assets:read`	Read asset data
`assets:write`	Create and modify assets
`members:read`	Read team member information
`offline_access`	Request refresh tokens

Service Tokens

Service tokens are designed for automated workflows and CI/CD pipelines. They provide non-expiring access with specific permissions.

Creating a Service Token

Go to Settings → API Keys → Service Tokens
Click Create Service Token
Configure:
- Name: Descriptive name for the token
- Permissions: Select required permissions
- IP Allowlist: (Optional) Restrict to specific IPs
Click Create

Using Service Tokens

Service tokens work the same as API keys:

curl -X GET "https://api.global.watch/v1/projects" \
  -H "Authorization: Bearer fw_service_abc123..."

IP Allowlisting

For enhanced security, restrict service tokens to specific IP addresses:

{
  "name": "CI/CD Pipeline Token",
  "permissions": ["projects:read", "assets:write"],
  "ip_allowlist": [
    "192.168.1.0/24",
    "10.0.0.1"
  ]
}

Security Best Practices

Token Storage

Environment	Recommended Storage
Server	Environment variables, secrets manager
CI/CD	Pipeline secrets (GitHub Actions, GitLab CI)
Local Development	`.env.local` file (gitignored)

Example: Secure Token Usage

// server-side only
import { GlobalWatch } from '@globalwatch/sdk';

// Load from environment
const client = new GlobalWatch({
  apiKey: process.env.GLOBALWATCH_API_KEY,
});

// Never log tokens
console.log('Connecting to Global Watch...'); // ✅
console.log(`Using key: ${apiKey}`); // ❌ Never do this

Handling Token Errors

Error Code	Description	Action
`401`	Invalid or expired token	Check token validity, refresh if OAuth
`403`	Insufficient permissions	Request additional scopes
`429`	Rate limit exceeded	Implement backoff, check limits

try {
  const projects = await client.projects.list();
} catch (error) {
  if (error.status === 401) {
    // Token expired - refresh or re-authenticate
    await refreshToken();
  } else if (error.status === 403) {
    // Insufficient permissions
    console.error('Missing required permissions');
  }
}

Testing Authentication

Verify Your Token

Test your authentication setup:

curl -X GET "https://api.global.watch/v1/auth/verify" \
  -H "Authorization: Bearer YOUR_TOKEN"

Success response:

{
  "valid": true,
  "type": "api_key",
  "permissions": ["projects:read", "projects:write", "assets:read"],
  "account_id": "acc_abc123",
  "expires_at": null
}

Common Issues

"Invalid token" error

Verify the token is copied correctly (no extra spaces)
Check if the token has been revoked
Ensure you're using the correct environment (production vs. development)

"Insufficient permissions" error

Review the token's granted permissions
Request additional scopes if using OAuth
Generate a new API key with required permissions

API Overview - Introduction to the Global Watch API
Endpoints - Available API endpoints
Webhooks - Event notifications

Authentication

On this page