Access control

Every action and query has an Access Control step with two parts. The Authorization Policy decides who may call it: anyone, signed-in users, or callers with certain roles. The Precondition decides when it may run, for example only while a case is open, or only for the caller’s own records. Both build on the caller information you define under Context.

Context: roles and user properties

Roles

Roles let actions and queries allow only some callers, for example a Partner role for a partner portal, or a SalesManager role for approvals. Add them under Context > Roles with Add role and a Role Name. Role names must be unique.

API roles are names that your API uses; they are not Dataverse security roles. Which roles a caller holds is decided by the API host when the caller signs in, so agree the role names with the team that runs the host. See Install and host Logic API.

User properties

User properties describe the caller, for access checks and filters, for example the customer number or the contact id of the signed-in user. Add them under Context > User with Add user property.

Column	Meaning
Name	How preconditions and queries refer to the property.
Type	The property’s data type.
Is List	The property holds several values, such as the ids of the accounts a partner manages.
Queryable	The property can be used in query conditions.
Nullable	The property may be empty.
Description	What the property holds.

Like roles, the values come from the API host when the caller signs in: its user resolver supplies them. A role or user property that is used anywhere in the API shows Used and cannot be deleted.

Authorization policy

1. Open the action or query and go to the Access Control step.
2. Under Authorization Policy, open Select Authorization Policy and choose a type.
3. For Demand User Role, pick the role. For Demand Any or Demand All, select Add Policy for each policy in the group.
4. Save.

Policy	Who may call
Demand User Role	Only callers that hold the role you pick.
Demand Authenticated User	Any signed-in caller.
Demand Anonymous User	Only callers that are not signed in.
Demand Any	A group of policies. The caller must satisfy at least one of them.
Demand All	A group of policies. The caller must satisfy each and every one of them.

Demand Any and Demand All are groups of policies, not lists of roles. Each policy in a group is a Demand User Role, Demand Authenticated User or Demand Anonymous User. For example:

• Demand Any with Demand User Role SalesManager and Demand User Role FinanceApprover: either role may approve.
• Demand All with Demand User Role Partner and Demand User Role CertifiedInstaller: the caller needs both roles.

Endpoints without a policy are public

No authorization policy means public

An action or query with no authorization policy can be called by anyone, signed in or not. In lists, its Access shows Anyone. Set a policy on every endpoint unless it is meant to be public (for example a product catalog), and review Anyone entries before you publish.

Incomplete policies are errors

An authorization policy that has no type, or a Demand Any / Demand All group with no policies in it, is an error:

• API Studio reports it as an issue on the Access Control step, so you can’t publish the draft until it is fixed.

Precondition

The precondition is a condition that must be true for the call to go ahead. It can combine several checks with and / or, and can use the caller’s inputs, the results of the action’s Data Fetcher queries, and the caller’s user properties.

Field	What it does
Condition	The check. When it is false, the call is refused.
Error Code	A code that identifies the failure for the caller, for example CREDIT_LIMIT_EXCEEDED. Callers receive it with status 400. If you leave it empty, callers receive CONDITION_VIOLATION.
Error Message	A message that explains the failure. Callers receive it with your error code.

Tip

Set an Error Code whenever you want callers to receive your Error Message. Without a code, callers receive CONDITION_VIOLATION with the standard message “API condition is not satisfied.” instead.

A precondition works with or without an authorization policy.

How it behaves

For every call, in this order:

1. The inputs are validated.
2. The Data Fetcher queries run.
3. The authorization policy is checked. If it fails, the caller gets 401 with UNAUTHORIZAD_ACCESS (spelled this way in the product).
4. The precondition is checked. If it is false, the call is refused with status 400 and your Error Code and Error Message (CONDITION_VIOLATION and “API condition is not satisfied.” when Error Code is empty).
5. Only then does the action or query run.

See Responses and errors for what callers receive.

Access column in lists

Access shows	Policy
Role	Demand User Role
Signed-in users	Demand Authenticated User
Signed-out users only	Demand Anonymous User
Any of several	Demand Any
All of several	Demand All
Anyone	No policy, so the endpoint is public

Example: partners update only their own opportunities

A partner portal lets partners update the estimated close date of opportunities they manage.

Part	Setting
Role	Partner
User property	accountId (Unique Identifier): the partner’s account, supplied by the host at sign-in
Data Fetcher	Look up the opportunity’s partner account and status.
Authorization Policy	Demand User Role Partner
Precondition	The opportunity is open and its partner account equals the caller’s accountId; Error Code NOT_YOUR_OPPORTUNITY; Error Message “You can only update open opportunities of your own account.”

A caller without the Partner role gets 401; a partner who tries to change another partner’s opportunity is refused by the precondition.

Related

• Actions
• Queries
• Responses and errors