Skip to main content

​
Overview

All DayCopilot API requests require authentication using JSON Web Tokens (JWT). The API uses Bearer token authentication in the Authorization header.

​
Getting Your Token

​
Via Dashboard

  1. Sign in to DayCopilot
  2. Navigate to your account settings
  3. Generate an API token
  4. Copy the JWT token for use in API requests
For third-party integrations and applications, use OAuth 2.0: 
# Step 1: Redirect users to authorization endpoint
https://app.daycopilot.ai/api/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=tasks:read tasks:write events:read events:write

# Step 2: Exchange authorization code for access token
curl -X POST "https://app.daycopilot.ai/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "v1.MRqKkv...",
  "scope": "tasks:read tasks:write events:read events:write"
}

​
Making Authenticated Requests

Include the JWT token in the Authorization header with the Bearer scheme: 
curl -X GET "https://app.daycopilot.ai/api/v1/tasks" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Token Security Best Practices

  • Never commit tokens to version control
  • Use environment variables or secure key management systems
  • Rotate tokens regularly (at least every 90 days)
  • Never expose tokens in client-side code or URLs
JWT tokens expire after a set period. Implement token refresh logic:
async function refreshToken(refreshToken) {
  const response = await fetch('https://app.daycopilot.ai/api/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken
    })
  });

  const { access_token } = await response.json();
  return access_token;
}
Always use HTTPS when making API requests. Never send tokens over unencrypted HTTP connections.
If a token is compromised, revoke it immediately:
curl -X POST "https://app.daycopilot.ai/api/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=YOUR_ACCESS_TOKEN"

​
OAuth 2.0 Scopes

DayCopilot supports fine-grained permissions via OAuth scopes:
ScopeDescription
tasks:readRead access to tasks
tasks:writeCreate, update, and delete tasks
events:readRead access to events
events:writeCreate, update, and delete events
contexts:readRead access to contexts
contexts:writeCreate, update, and delete contexts
user:readRead user profile information
user:writeUpdate user profile information
Request only the scopes your application needs: 
scope=tasks:read tasks:write events:read

​
Access Control

All API requests are automatically scoped to the authenticated user via access control policies:
  • Users can only access their own data
  • Users can access data explicitly shared with them
  • Collaborative contexts respect sharing permissions
  • All queries are filtered by user context
This means you don’t need to manually filter by user ID - access control is handled automatically. See Access Control & Permissions for detailed information.

​
Error Responses

​
401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Missing or invalid authentication token",
  "status": 401
}
Causes:
  • Missing Authorization header
  • Invalid or expired token
  • Malformed token

​
403 Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions to access this resource",
  "status": 403
}
Causes:
  • Valid token but insufficient OAuth scopes
  • Attempting to access another user’s data
  • Resource not shared with authenticated user

​
Testing Authentication

Use this endpoint to verify your token is valid: 
curl -X GET "https://app.daycopilot.ai/api/oauth/userinfo" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2025-01-15T10:00:00Z"
}

​
Next Steps

Quick Start

Make your first authenticated API call

API Reference

Explore authenticated endpoints