Authentication

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

Sign in to DayCopilot
Navigate to your account settings
Generate an API token
Copy the JWT token for use in API requests

Via OAuth 2.0 (Recommended for integrations)

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"

const response = await fetch('https://app.daycopilot.ai/api/v1/tasks', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

import requests

headers = {
    'Authorization': f'Bearer {token}'
}
response = requests.get('https://app.daycopilot.ai/api/v1/tasks', headers=headers)

Token Security Best Practices

Store Tokens Securely

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

Handle Token Expiration

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;
}

Use HTTPS Only

Always use HTTPS when making API requests. Never send tokens over unencrypted HTTP connections.

Implement Token Revocation

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:

Scope	Description
`tasks:read`	Read access to tasks
`tasks:write`	Create, update, and delete tasks
`events:read`	Read access to events
`events:write`	Create, update, and delete events
`contexts:read`	Read access to contexts
`contexts:write`	Create, update, and delete contexts
`user:read`	Read user profile information
`user:write`	Update 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"
}

Getting Started

Core Concepts

Guides

Resources

Overview

Getting Your Token

Via Dashboard

Via OAuth 2.0 (Recommended for integrations)

Making Authenticated Requests

Token Security Best Practices

OAuth 2.0 Scopes

Access Control

Error Responses

401 Unauthorized

403 Forbidden

Testing Authentication

Next Steps

Quick Start

API Reference

​Overview

​Getting Your Token

​Via Dashboard

​Via OAuth 2.0 (Recommended for integrations)

​Making Authenticated Requests

​Token Security Best Practices

​OAuth 2.0 Scopes

​Access Control

​Error Responses

​401 Unauthorized

​403 Forbidden

​Testing Authentication

​Next Steps

Quick Start

API Reference

Overview

Getting Your Token

Via Dashboard

Via OAuth 2.0 (Recommended for integrations)

Making Authenticated Requests

Token Security Best Practices

OAuth 2.0 Scopes

Access Control

Error Responses

401 Unauthorized

403 Forbidden

Testing Authentication

Next Steps