> This page is for Developers. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.emnify.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emnify.com/_mcp/server. # Permissions > How API authorization works, including resource and action permissions and the system roles that grant them. Almost every request to the emnify API is authorized against a single permission. A few endpoints need none: public ones such as authentication, and a handful that only require a signed-in user. If your role doesn't include the permission an endpoint requires, the API responds with [`403 Forbidden`](/developers/api-guidelines/errors#permission-errors). Each endpoint's required permission is shown in a callout at the top of its reference page. For endpoints that require no permission, such as authentication, the callout says so. For every permission at once, and the roles that include it, see the [permission reference](#permission-reference). Some permissions grant more than one endpoint, and [Endpoints by permission](/developers/api-guidelines/permission-endpoints) lists them. > **Note** > > Permissions are in beta. To request access, contact your Customer Success Manager. ## How permissions work A permission is a pair of a *resource* (the thing you act on) and an *action* (what you do to it). In these docs it's written as `Resource` + `Action`, for example `Endpoint` + `List`. You always need the exact pair. Permissions are grouped into roles, and every user is assigned a role: * **System roles** are built in and can't be edited: Administrator, User, and Observer. Each includes a fixed set of permissions. * **Custom roles** let you grant an exact set of permissions that you choose. To call an endpoint, your role must include that endpoint's required permission. [Roles and permissions](/portal/roles) documents what each system role includes in the emnify Portal. A custom role grants whatever combination you choose. ## The permission model | Concept | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Resource | The domain you act on, in PascalCase with dots for hierarchy, such as `Endpoint`, `Endpoint.Tag`, or `User.Mfa`. | | Action | The operation, such as `List`, `Get`, `Create`, `Update`, `Delete`, `Add`, `Remove`, or a specific verb like `Transfer` or `Cancel`. | | Pair | A permission is always a resource and an action together. Neither half grants access on its own. | | Own data | Some resources have a `.My` variant for acting on your own data, such as your own user, separate from acting on others'. | | Bulk endpoints | A bulk endpoint uses the same permission as its single-resource version. For example, `DELETE /api/v1/endpoint/multi` and `DELETE /api/v1/endpoint/{endpoint_id}` both require `Endpoint` + `Delete`. | | Public endpoints | A few endpoints, such as authentication, require no permission. | ## System roles | Role | Access | | ------------- | --------------------------------------------------------------------------------------- | | Administrator | Full access to every permission. | | User | Day-to-day access: all read actions, plus write actions that are safe to grant broadly. | | Observer | Read-only access. | To grant a different combination, [create a custom role](/developers/api-guidelines/manage-permissions) from the permissions in the reference below. For ready-made permission sets covering three common jobs, see [Role templates](/developers/api-guidelines/role-templates). ## Permission reference > **Note** > > This reference covers the emnify REST API. Permissions for pre-release APIs are added when those APIs become generally available. The table lists each API permission and which system roles include it. `ApplicationToken` `CallbackSecret` `CallbackUrl` `CloudConnect.Breakout` `DataStream` `Dns` `DnsFirewallProfile` `Endpoint` `Endpoint.Connectivity` `Endpoint.OperatorBlacklist` `Endpoint.Quota.Data` `Endpoint.Quota.Sms` `Endpoint.Sms` `Endpoint.Tag` `Endpoint.TrafficLimitExtension` `IpAddressSpace` `IpFirewallProfile` `Organisation.InclusiveVolume` `Organisation.Role` `ServiceProfile` `ServiceProfile.D2d` `ServiceProfile.Service` `ServiceProfile.Service.TrafficLimit` `ServiceProfile.TrafficLimit` `Sim` `SimBatch.Bic` `Tag` `TariffProfile` `TariffProfile.InclusiveVolume` `TariffProfile.OperatorBlocklist.Operator` `TariffProfile.OperatorBlocklist.Operator.RatType` `TariffProfile.RatezoneSelection` `User` `User.Mfa.TrustedDevice` `User.Role` `User.Workspace` `User.Workspace.Role`
Resource Action Administrator User Observer
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes No No
`Update` Yes No No
`Delete` Yes No No
`ApplicationToken.Status` `List` Yes Yes Yes
`Authenticate.Workspace` `Get` Yes Yes Yes
`BreakoutRegion` `List` Yes Yes Yes
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes Yes No
`Delete` Yes Yes No
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes Yes No
`Delete` Yes Yes No
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes Yes No
`Delete` Yes No No
`CloudConnect.Breakout.Tgw` `Create` Yes Yes No
`CloudConnect.Breakout.Vpn` `Create` Yes Yes No
`CloudConnect.BreakoutType` `List` Yes Yes Yes
`CloudConnect.BreakoutType.Region` `List` Yes Yes Yes
`CloudConnect.Pricing` `List` Yes Yes Yes
`Country` `List` Yes Yes Yes
`Currency` `List` Yes Yes Yes
`DataBlocksize` `List` Yes Yes Yes
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes Yes No
`Update` Yes Yes No
`Delete` Yes Yes No
`Restart` Yes Yes No
`DataStream.FilterFieldType` `List` Yes Yes Yes
`DataStream.Status` `List` Yes Yes Yes
`DataStream.Type` `List` Yes Yes Yes
`DataThrottle` `List` Yes Yes Yes
`List` Yes Yes No
`Create` Yes Yes No
`Delete` Yes Yes No
`List` Yes No No
`Get` Yes No No
`Create` Yes No No
`Update` Yes No No
`Delete` Yes No No
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes Yes No
`Update` Yes Yes No
`Delete` Yes Yes No
`Get` Yes Yes Yes
`Update` Yes Yes No
`Endpoint.Event` `List` Yes Yes Yes
`Endpoint.FlowLogs.Destination` `List` Yes No No
`Endpoint.FlowLogs.Detail` `List` Yes No No
`List` Yes Yes Yes
`Delete` Yes Yes No
`Add` Yes Yes No
`Get` Yes Yes Yes
`Create` Yes Yes No
`Delete` Yes Yes No
`Get` Yes Yes Yes
`Create` Yes Yes No
`Delete` Yes Yes No
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes Yes No
`Cancel` Yes Yes No
`Endpoint.Stats` `Get` Yes Yes Yes
`Endpoint.Status` `List` Yes Yes Yes
`List` Yes Yes Yes
`Add` Yes Yes No
`Remove` Yes Yes No
`List` Yes Yes Yes
`Create` Yes Yes No
`Delete` Yes Yes No
`EsmeInterfaceType` `List` Yes Yes Yes
`Event` `List` Yes Yes Yes
`Event.Type` `List` Yes Yes Yes
`List` Yes Yes Yes
`Create` Yes No No
`Add` Yes No No
`Remove` Yes No No
`List` Yes No No
`Create` Yes No No
`Operator` `List` Yes Yes Yes
`List` Yes Yes Yes
`Add` Yes Yes No
`Organisation.My` `Get` Yes Yes Yes
`Organisation.Permission` `List` Yes No No
`List` Yes Yes No
`Get` Yes Yes No
`Create` Yes No No
`Update` Yes No No
`Delete` Yes No No
`Organisation.Stats` `Get` Yes Yes Yes
`Organisation.Status` `List` Yes Yes Yes
`Organisation.Tariff` `Update` Yes Yes No
`Organisation.TariffPlan` `List` Yes Yes Yes
`RatType` `List` Yes Yes Yes
`Service` `List` Yes Yes Yes
`Service.TrafficLimit` `List` Yes Yes Yes
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes Yes No
`Update` Yes Yes No
`Delete` Yes Yes No
`Get` Yes No No
`Update` Yes No No
`ServiceProfile.DnsFirewallRuleSet` `Update` Yes No No
`ServiceProfile.Quota` `Remove` Yes Yes No
`Add` Yes Yes No
`Remove` Yes Yes No
`Delete` Yes Yes No
`Add` Yes Yes No
`List` Yes Yes Yes
`Create` Yes Yes No
`Delete` Yes Yes No
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Update` Yes Yes No
`Delete` Yes Yes No
`Sim.Event` `List` Yes Yes Yes
`Sim.Stats` `Get` Yes Yes Yes
`Sim.Status` `List` Yes Yes Yes
`Sim.Workspace` `Transfer` Yes No No
`Get` Yes Yes Yes
`Add` Yes Yes No
`List` Yes Yes Yes
`Create` Yes Yes No
`Update` Yes Yes No
`Delete` Yes Yes No
`Tag.Color` `List` Yes Yes Yes
`TariffPlan` `List` Yes Yes Yes
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Create` Yes Yes No
`Update` Yes Yes No
`Delete` Yes Yes No
`TariffProfile.Coverage` `List` Yes Yes Yes
`Add` Yes Yes No
`Remove` Yes Yes No
`List` Yes Yes Yes
`Get` Yes Yes Yes
`Add` Yes Yes No
`Remove` Yes Yes No
`Add` Yes Yes No
`Remove` Yes Yes No
`Add` Yes Yes No
`Remove` Yes Yes No
`TrafficLimit` `List` Yes Yes Yes
`List` Yes No No
`Get` Yes No No
`Create` Yes No No
`Update` Yes No No
`Delete` Yes No No
`User.DefaultOrganisation` `Update` Yes No No
`User.Event` `List` Yes No No
`User.Invitation` `Create` Yes No No
`User.Mfa` `Delete` Yes Yes Yes
`User.Mfa.Status` `List` Yes Yes Yes
`List` Yes No No
`Delete` Yes No No
`User.Mfa.Type` `List` Yes Yes Yes
`User.My.Role` `List` Yes Yes No
`Add` Yes No No
`Remove` Yes No No
`User.Role.Permission` `List` Yes No No
`User.Status` `List` Yes Yes Yes
`List` Yes Yes Yes
`Update` Yes No No
`Remove` Yes No No
`Add` Yes No No
`Remove` Yes No No