Authorization

Authorization in the Accomplish API is implemented through a granular scope-based system that controls access to different resources and operations. After authentication (proving who you are), authorization determines what actions you're allowed to perform based on the scopes assigned to your API key.

This approach follows the principle of least privilege - API keys are granted only the minimum permissions necessary for their intended use case. Scopes can be combined to create fine-grained access control, allowing you to restrict API keys to specific resources (projects, repositories, worklog entries) and operations (read, write).

Scope Format

Scopes follow the pattern resource:permission, where:

• Resource - The API resource type (user, project, repo, worklog)
• Permission - The access level (read, write, or * for all permissions)

Wildcard Scopes

You can use wildcard scopes to grant all permissions within a resource category:

• project:* - Grants both project:read and project:write
• repo:* - Grants both repo:read and repo:write
• worklog:* - Grants both worklog:read and worklog:write
• user:* - Grants both user:read and user:write

Note: Cross-resource wildcards like *:read or *:* are not supported.

Available Scopes

User Scopes

Scope	Description	Endpoints
user:read	View and retrieve user profile and account information	GET /api/v1/user
user:write	Create, update, and delete user data	PUT /api/v1/user DELETE /api/v1/user
user:*	All user permissions (combines read and write)	All user endpoints

Project Scopes

Scope	Description	Endpoints
project:read	View and retrieve project data	GET /api/v1/projects GET /api/v1/projects/{id}
project:write	Create, update, and delete projects	POST /api/v1/projects PUT /api/v1/projects/{id} DELETE /api/v1/projects/{id}
project:*	All project permissions (combines read and write)	All project endpoints

Repository Scopes

Scope	Description	Endpoints
repo:read	View and retrieve repository information and commits	GET /api/v1/repositories GET /api/v1/repositories/{id} GET /api/v1/repositories/{id}/commits
repo:write	Create, update, and delete repository data	POST /api/v1/projects/{id}/repositories POST /api/v1/repositories PUT /api/v1/repositories/{id} DELETE /api/v1/repositories/{id} POST /api/v1/repositories/{id}/commits
repo:*	All repository permissions (combines read and write)	All repository endpoints

Worklog Scopes

Scope	Description	Endpoints
worklog:read	View and retrieve worklog entries and time tracking data	GET /api/v1/worklog/entries GET /api/v1/worklog/entries/{id} GET /api/v1/worklog/recaps/{id} GET /api/v1/worklog/recaps/sse
worklog:write	Create, update, and delete worklog entries	POST /api/v1/worklog/entries PUT /api/v1/worklog/entries/{id} DELETE /api/v1/worklog/entries/{id} POST /api/v1/worklog/entries/{id}/commits POST /api/v1/worklog/recaps
worklog:*	All worklog permissions (combines read and write)	All worklog endpoints

Scope Combinations

You can combine multiple scopes when creating an API key. Common combinations include:

Read-Only Access

user:read, project:read, repo:read, worklog:read

Perfect for analytics, reporting, or dashboard applications that only need to view data.

Project Management

project:*, repo:*

Ideal for project management tools that need full control over projects and repositories but not user data or worklogs.

Full Worklog Access

project:read, worklog:*

Suitable for time tracking applications that need to read project information and fully manage worklog entries.

Complete Access

user:*, project:*, repo:*, worklog:*

Full API access using wildcards - use with caution and only when necessary.

Legacy Explicit Access

user:read, user:write, project:read, project:write, repo:read, repo:write, worklog:read, worklog:write

Same as complete access but explicitly listing each permission instead of using wildcards.

Best Practices

Principle of Least Privilege

• Only grant the minimum scopes required for your application
• Regularly review and update scope assignments
• Use read-only scopes when write access isn't needed

Scope Planning

• Analytics dashboards - Use read-only scopes (*:read)
• Backup tools - Use read-only scopes for all relevant resources
• Integration platforms - Use specific scopes based on required operations
• Mobile apps - Limit to user-specific operations, avoid admin scopes

Security Considerations

• Write scopes (*:write) allow data modification - use carefully
• User write scopes can modify sensitive account information
• Repository write scopes can create and modify git data
• Worklog write scopes can alter time tracking and productivity data

Error Responses

When an API key lacks the required scope for an endpoint, you'll receive a 403 Forbidden response:

{
  "error": "Insufficient permissions for this endpoint",
  "details": {
    "required_scope": "project:write",
    "granted_scopes": ["project:read", "worklog:read"]
  }
}

This response includes:

• required_scope - The minimum scope needed for the operation
• granted_scopes - The scopes currently assigned to your API key

Managing Scopes

Updating API Key Scopes

To change the scopes for an existing API key:

1. Go to Settings → API Keys in the Accomplish app
2. Delete the existing API key
3. Create a new API key with the desired scopes
4. Update your application with the new key

Note: There's currently no way to modify scopes for existing keys - you must create a new key.

Scope Validation

When creating an API key, the system validates:

• All selected scopes are valid and recognized
• Scope combinations are logically consistent
• You have permission to grant the requested scopes