Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.linkutm.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Permissions are derived from a user’s role in a workspace. Each workspace membership has a role, and each role grants a fixed set of permission actions. These endpoints let you read the caller’s effective permissions for a given workspace. Endpoints live under /api/v1/permissions and require a JWT bearer token plus the x-workspace-id header. 
Authorization: Bearer <jwt>
x-workspace-id: <uuid_or_slug>
Permissions are resolved from the caller’s WorkspaceMember record for the workspace in x-workspace-id. If the caller is not a member of that workspace, an empty permission set is returned - the endpoints do not error in that case.

​
Get my permissions

GET /api/v1/permissions/mine
Returns the array of permission actions the authenticated user holds in the workspace named by x-workspace-id.

​
Headers

HeaderRequiredNotes
Authorization: Bearer <jwt>Yes
x-workspace-id: <uuid_or_slug>YesTarget workspace, by UUID or slug

​
Example request

curl https://api.linkutm.com/api/v1/permissions/mine \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-workspace-id: client-globex"

​
Example response

A JSON array of permission action strings. 
[
  "utm_templates.create",
  "utm_templates.edit",
  "utm_templates.delete",
  "links.create",
  "links.edit",
  "analytics.view",
  "data.export"
]
If the caller is not a member of the workspace, the response is an empty array [].

​
Check a permission

GET /api/v1/permissions/check?action=<permission>
Checks whether the authenticated user holds one specific permission action in the workspace named by x-workspace-id.

​
Headers

HeaderRequiredNotes
Authorization: Bearer <jwt>Yes
x-workspace-id: <uuid_or_slug>YesTarget workspace, by UUID or slug

​
Query parameters

​
action
string
required
The permission action to check, for example links.create. See the permission actions table for valid values.

​
Example request

curl "https://api.linkutm.com/api/v1/permissions/check?action=links.delete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-workspace-id: client-globex"

​
Example response

{ "hasPermission": false }
hasPermission is true only when the caller’s role in the workspace includes the requested action. A missing or unknown action value returns false; the endpoint does not reject it.

​
Permission actions

The full set of permission actions:
ActionDescription
workspace.manageManage workspace settings
billing.manageUpgrade or downgrade the plan
domains.createAdd a custom domain
domains.updateUpdate a custom domain
domains.deleteDelete a custom domain
team.inviteInvite team members
team.removeRemove team members
utm_rules.manageDefine and edit UTM rules
utm_templates.createCreate UTM templates
utm_templates.editEdit UTM templates
utm_templates.deleteDelete UTM templates
links.createCreate links
links.editEdit links
links.deleteDelete links
links.importImport links
analytics.viewView link click analytics and GA4 data
data.exportExport data as CSV
api_keys.manageManage API keys

​
Roles and their permissions

There are four built-in roles. The table below shows the default permission set granted to each.
Permission actionowneradminmemberviewer
workspace.manageYes---
billing.manageYes---
domains.createYesYes--
domains.updateYesYes--
domains.deleteYesYes--
team.inviteYesYes--
team.removeYesYes--
utm_rules.manageYesYes--
utm_templates.createYesYesYes-
utm_templates.editYesYesYes-
utm_templates.deleteYesYesYes-
links.createYesYesYes-
links.editYesYesYes-
links.deleteYesYes--
links.importYesYes--
analytics.viewYesYesYesYes
data.exportYesYesYes-
api_keys.manageYesYes--

​
Role summary

Full access. Holds every permission action, including workspace.manage and billing.manage, which no other role has.
Holds every permission except workspace.manage and billing.manage. Can manage domains, team, UTM rules, links, API keys, analytics, and exports.
Can create and edit links, manage UTM templates, view analytics, and export data. Cannot delete or import links, manage domains, manage team, manage UTM rules, or manage API keys.
Read-only. Holds analytics.view only.
The table above lists the default role to permission mapping. Effective permissions are read from the RolePermission records at runtime, so a workspace’s actual mapping may differ if it has been customized.

​
Errors

CodeWhen
401Missing or invalid JWT
429Rate limit exceeded (100 requests/minute per IP)
See Errors for the full error envelope.