API Scopes Reference¶

API scopes define the permissions granted to an API key. Each scope allows access to specific operations on specific resources.

Scope Format¶

Scopes follow the pattern resource:action:

Resource: The type of data (e.g., tickets, users)
Action: The operation type (read, write, delete)

Available Scopes¶

Tickets¶

Scope	Description	Operations
`tickets:read`	View tickets	List tickets, get ticket details
`tickets:write`	Create and update tickets	Create new tickets, update existing tickets
`tickets:delete`	Delete tickets	Permanently delete tickets

Comments¶

Scope	Description	Operations
`comments:read`	View comments	List comments, get comment details
`comments:write`	Create and update comments	Add comments, edit comments
`comments:delete`	Delete comments	Remove comments from tickets

Attachments¶

Scope	Description	Operations
`attachments:read`	View and download attachments	List attachments, get download URLs
`attachments:write`	Upload attachments	Upload files to tickets
`attachments:delete`	Delete attachments	Remove attachments

Customers¶

Scope	Description	Operations
`customers:read`	View customers	List customers, get customer details
`customers:write`	Create and update customers	Create customers, update profiles
`customers:delete`	Delete customers	Remove customer records

Teams¶

Scope	Description	Operations
`teams:read`	View teams	List teams, get team details and members
`teams:write`	Manage teams	Create teams, update, add/remove members
`teams:delete`	Delete teams	Remove teams

Users¶

Scope	Description	Operations
`users:read`	View users	List users, get user details
`users:write`	Manage users	Create users, update profiles, manage avatars
`users:delete`	Delete users	Remove user accounts

Dashboard¶

Scope	Description	Operations
`dashboard:read`	View dashboard data	Get statistics, metrics, activity feeds

Scope Groups¶

Read-Only Scopes¶

These scopes provide view-only access:

tickets:read
comments:read
attachments:read
customers:read
teams:read
users:read
dashboard:read

Read-Only Admin Keys

Users with the read_only_admin role can only create API keys with these read-only scopes.

Full Access Scopes¶

All available scopes:

tickets:read
tickets:write
tickets:delete
comments:read
comments:write
comments:delete
attachments:read
attachments:write
attachments:delete
customers:read
customers:write
customers:delete
teams:read
teams:write
teams:delete
users:read
users:write
users:delete
dashboard:read

Endpoint Requirements¶

Tickets Endpoints¶

Endpoint	Method	Required Scope
`/v1/tickets`	GET	`tickets:read`
`/v1/tickets/{id}`	GET	`tickets:read`
`/v1/tickets`	POST	`tickets:write`
`/v1/tickets/{id}`	PATCH	`tickets:write`
`/v1/tickets/{id}`	DELETE	`tickets:delete`

Comments Endpoints¶

Endpoint	Method	Required Scope
`/v1/tickets/{id}/comments`	GET	`comments:read`
`/v1/tickets/{id}/comments/{id}`	GET	`comments:read`
`/v1/tickets/{id}/comments`	POST	`comments:write`
`/v1/tickets/{id}/comments/{id}`	PATCH	`comments:write`
`/v1/tickets/{id}/comments/{id}`	DELETE	`comments:delete`

Attachments Endpoints¶

Endpoint	Method	Required Scope
`/v1/tickets/{id}/attachments`	GET	`attachments:read`
`/v1/tickets/{id}/attachments/{id}`	GET	`attachments:read`
`/v1/tickets/{id}/attachments/{id}/download`	GET	`attachments:read`
`/v1/tickets/{id}/attachments`	POST	`attachments:write`
`/v1/tickets/{id}/attachments/{id}`	DELETE	`attachments:delete`

Customers Endpoints¶

Endpoint	Method	Required Scope
`/v1/customers`	GET	`customers:read`
`/v1/customers/{id}`	GET	`customers:read`
`/v1/customers`	POST	`customers:write`
`/v1/customers/{id}`	PATCH	`customers:write`
`/v1/customers/{id}`	DELETE	`customers:delete`

Teams Endpoints¶

Endpoint	Method	Required Scope
`/v1/teams`	GET	`teams:read`
`/v1/teams/{id}`	GET	`teams:read`
`/v1/teams`	POST	`teams:write`
`/v1/teams/{id}`	PATCH	`teams:write`
`/v1/teams/{id}`	DELETE	`teams:delete`
`/v1/teams/{id}/members`	POST	`teams:write`
`/v1/teams/{id}/members/{id}`	DELETE	`teams:write`

Users Endpoints¶

Endpoint	Method	Required Scope
`/v1/users`	GET	`users:read`
`/v1/users/{id}`	GET	`users:read`
`/v1/users`	POST	`users:write`
`/v1/users/{id}`	PATCH	`users:write`
`/v1/users/{id}`	DELETE	`users:delete`
`/v1/users/me/avatar`	POST	`users:write`
`/v1/users/me/avatar`	DELETE	`users:write`

Dashboard Endpoints¶

Endpoint	Method	Required Scope
`/v1/dashboard/stats`	GET	`dashboard:read`
`/v1/dashboard/activity`	GET	`dashboard:read`
`/v1/dashboard/ticket-trends`	GET	`dashboard:read`

Search Endpoints¶

Endpoint	Method	Required Scope
`/v1/search`	GET	`tickets:read`

Common Scope Combinations¶

Ticket Management¶

For creating and managing tickets:

["tickets:read", "tickets:write", "comments:read", "comments:write"]

Read-Only Dashboard¶

For viewing data without modifications:

["tickets:read", "customers:read", "dashboard:read"]

Full Support Agent¶

For full support operations:

[
  "tickets:read", "tickets:write",
  "comments:read", "comments:write",
  "attachments:read", "attachments:write",
  "customers:read", "customers:write"
]

Integration Sync¶

For syncing data to external systems:

["tickets:read", "customers:read", "users:read", "teams:read"]

Error Messages¶

Missing Scope¶

When you lack the required scope:

{
  "detail": "Insufficient permissions. Required scope: tickets:write"
}

Invalid Scope¶

When requesting an invalid scope during key creation:

{
  "detail": [
    {
      "loc": ["body", "scopes", 0],
      "msg": "Invalid scope: tickets:admin",
      "type": "value_error"
    }
  ]
}

Best Practices¶

Principle of Least Privilege¶

Only request scopes you actually need:

# Good: minimal required scopes
scopes = ["tickets:read", "tickets:write"]

# Avoid: requesting all scopes "just in case"
scopes = ["tickets:read", "tickets:write", "tickets:delete", ...]

Separate Keys for Different Uses¶

Create separate API keys for different purposes:

Reporting key: Read-only scopes
Automation key: Specific write scopes needed
Admin key: Full access for administrative tasks

Regular Audits¶

Review your API keys and their scopes periodically to ensure they still match your needs.