API Access Policies

Evaluation model

Before issuing an access token for an API, MonoCloud builds a Cedar authorization request:

• Principal: Client::"<client id>", including its client groups as parent entities.
• Action: Action::"IssueAccessToken".
• Resource: Api::"<audience>", representing the API resource being evaluated.
• Context: request-time attributes such as the user, grant type, requested scopes, location, time, and client certificate. See Context attributes for the full reference.

All enabled policies attached to the API resource are evaluated together.

When a request includes multiple API audiences, MonoCloud evaluates policies for each API independently. Policies for an API are evaluated only when that API is requested as an audience.

Entities

Policy conditions can reference the following entity types:

Context attributes

Basic and advanced policies

You can create policies in two modes:

• Basic - configured in the dashboard using structured settings for the client, allowed scopes, and permit or deny effect. MonoCloud compiles the policy to Cedar. A basic permit policy matches when the configured client requests an access token for the API and, when allowed scopes are configured, every requested scope for that API is in the allowed list. Leave the allowed-scopes list empty to allow any scope defined by the API.
• Advanced - authored directly in Cedar against the schema described above. Advanced policies support conditions based on user groups, time, location, network zones, client certificates, authentication recency, and more. Advanced deny policies can also return a custom denial message to the client.

You do not need to write Cedar from scratch. In the dashboard's advanced rule editor, you can start with a sample policy for common scenarios or generate a Cedar policy with AI assistance. Describe the rule in plain English, such as “Allow billing admins during business hours from corporate IPs,” then review and refine the generated draft.

MonoCloud validates every advanced policy against the schema before it can be saved, catching invalid attribute names, entity types, and other schema errors before the policy is evaluated.

For example, a basic permit policy for web-client on https://api.example.com/billing, allowing the read and write scopes, compiles to:

permit (
  principal == Client::"web-client",
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context.requested_audiences.contains(resource) &&
  [
    Scope::"https://api.example.com/billing#read",
    Scope::"https://api.example.com/billing#write"
  ].containsAll(context.requested_api_scopes)
};

Token behavior overrides

Each API resource defines default token settings. A permitting policy can override those settings for requests it matches.

When multiple permit policies match the same request, MonoCloud merges their effective settings using the restrictive rules below. Before merging, any setting left unset by a policy inherits the API resource default.

Multiple permit policies can match the same request, for example, when both a broad client-group policy and a more specific client policy apply. MonoCloud merges their settings so that the most restrictive effective value takes precedence.

For example, when the API resource default is AllowUserInfoAccess=false, a permitting policy that leaves AllowUserInfoAccess unset inherits false. It therefore contributes false to the merge, and UserInfo access remains disabled unless every matching policy resolves to true.

Granting baseline access

Use a permit policy to allow a specific client to obtain access tokens for an API:

permit (
  principal == Client::"backend-worker",
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
);

To allow all clients in a client group, match the principal against the group instead:

permit (
  principal in Group::"Billing Admins",
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
);

Restricting scopes

Permit all clients in the First Party client group to request only the read and write scopes:

permit (
  principal in Group::"First Party",
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  [
    Scope::"https://api.example.com/billing#read",
    Scope::"https://api.example.com/billing#write"
  ].containsAll(context.requested_api_scopes)
};

containsAll requires the requested API scopes to be a subset of the allowed scopes. If the request includes any scope outside this list, the policy does not match.

To match a scope by its raw name without specifying the audience, use context.requested_scope_names. For example, deny issuing a token whenever a privileged scope is requested anywhere in the call:

forbid (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context.requested_scope_names.contains("admin")
};

context.requested_scope_names holds the raw names of every requested scope (identity and API, for any audience), so this matches an admin scope no matter which API defines it. Because names are merged across APIs, use the audience-qualified Scope::"..." form above when you need to restrict a specific API's scopes.

Restricting by requested audience

context.requested_audiences is the set of all API audiences requested in the current call. Beyond the baseline context.requested_audiences.contains(resource) guard, you can use it to control which APIs may share a single token.

For example, deny issuing a token for this API whenever a more privileged API is requested in the same call:

forbid (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context.requested_audiences.contains(Api::"https://api.example.com/admin")
};

Because a matching forbid always takes precedence, the request is denied whenever both the billing and admin audiences are requested together, preventing the two from sharing an access token.

Restricting by user

Permit access only to a specific user by their user id:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context has user &&
  context.user == User::"3f9a8b7c-1e2d-4a5b-9c8d-7e6f5a4b3c2d"
};

Each user is identified as User::"<user id>", so match context.user against the user's id to scope access to an individual user.

Machine-to-machine requests do not include a user. A user may also be absent during an authorization request, before the user has authenticated. Guard conditions that reference context.user with context has user.

Permit access only to a specific user by their primary email address:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context has user &&
  context.user has email &&
  context.user.email == "admin@example.com"
};

context.user.email holds the user's primary email address. It is optional, so guard it with context.user has email (in addition to context has user). A user without a primary email has no email attribute, and email comparisons are case-sensitive.

Permit access only when the authenticated user belongs to a specific group:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context has user &&
  context.user in Group::"Billing Admins"
};

Requiring recent authentication

Require that the user authenticated within the last 12 hours:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context has authentication &&
  context.now.durationSince(context.authentication.auth_time) <= duration("12h")
};

Authentication context is available only after a user has authenticated. Guard conditions that reference context.authentication with context has authentication.

Restricting by network and location

Permit access only when the request originates from a named network zone:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context.network_zones.contains(NetworkZone::"office")
};

Use containsAny to allow requests from any of several trusted zones, or containsAll to require that all specified zones match.

Permit access only when the request IP address falls within a specific range:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context.location.ip_address.isInRange(ip("203.0.113.0/24"))
};

Deny requests originating outside approved countries:

forbid (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
unless {
  [Country::"US", Country::"CA"].contains(context.location.country)
};

unless means this policy forbids the request unless the resolved country is in the approved list.

Because a forbid policy overrides any matching permit policy, this rule denies the request even when another policy allows it. Use a custom denial message on the policy to help callers understand why access was denied.

Restricting by time

Permit access only on weekdays between 09:00 and 17:00 UTC:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  [
    DayOfWeek::"monday",
    DayOfWeek::"tuesday",
    DayOfWeek::"wednesday",
    DayOfWeek::"thursday",
    DayOfWeek::"friday"
  ].contains(context.day_of_week) &&
  context.time_of_day_seconds >= 32400 && // 09:00 UTC
  context.time_of_day_seconds < 61200     // 17:00 UTC
};

Grant access only until a specified date and time:

permit (
  principal == Client::"contractor-app",
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context.now < datetime("2026-12-31T23:59:59Z")
};

All time-based context attributes are evaluated in UTC.

Requiring mTLS client certificates

Permit access only to workloads that present a client certificate validated by a specific trust store and with the expected subject distinguished name:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/orders"
)
when {
  context has certificate &&
  context.certificate.trust_store == TrustStore::"mihpmRHX1ApWIZDyugVQ2" &&
  context.certificate.subject_dn == "CN=orders-worker,OU=production,O=example.com"
};

For workloads using SPIFFE X.509 SVIDs, match the SPIFFE ID in the certificate’s URI SAN instead:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/orders"
)
when {
  context has certificate &&
  context.certificate.trust_store == TrustStore::"r2dzFrCfgU1aX5nTQUTS4" &&
  context.certificate.san_uris.contains("spiffe://example.com/ns/orders/sa/worker")
};

The certificate context is available only when the client authenticates with mTLS. Guard conditions that reference context.certificate with context has certificate.

Restricting by workload identity

When a client authenticates using workload identity, the request includes its SPIFFE ID. This can apply to both application and agent clients.

To permit only a specific workload identity:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/orders"
)
when {
  context has spiffe_id &&
  context.spiffe_id == "spiffe://example.com/ns/orders/sa/worker"
};

context.spiffe_id is available only for workload-identity requests, so guard conditions that reference it with context has spiffe_id.

Restricting by grant type

Permit only machine-to-machine access using the client credentials grant:

permit (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/internal"
)
when {
  context.grant_type == GrantType::"client_credentials"
};

Use context.grant_type to control which OAuth grants can obtain access tokens for an API. For example, you can allow client_credentials for service-to-service access while requiring user-centric grants for APIs that act on behalf of a user.

To explicitly block a grant type, add a forbid policy. This example prevents password-grant requests from obtaining a token for the API:

forbid (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/internal"
)
when {
  context.grant_type == GrantType::"password"
};

A matching forbid policy takes precedence over any matching permit policy.

Combining permits and forbids

A common pattern is to combine a broad permit policy with targeted forbid policies that enforce hard restrictions.

// Policy 1: Allow clients in the First Party group to access the API
permit (
  principal in Group::"First Party",
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
);

// Policy 2: Deny requests from blocked network zones
forbid (
  principal,
  action == Action::"IssueAccessToken",
  resource == Api::"https://api.example.com/billing"
)
when {
  context.network_zones.contains(NetworkZone::"blocked")
};

A request from a client in the First Party group in the blocked network zone matches both policies. MonoCloud denies the request because a matching forbid policy always takes precedence over a matching permit policy.

Shaping the token

A permitting policy can also apply token settings to the requests it matches.

For example, suppose the billing API defaults to one-hour JWT access tokens. To issue short-lived, session-bound reference tokens for browser-based requests, configure a permit policy with:

• Condition: context.caller_type == CallerType::"browser"
• Token settings: AccessTokenType=reference, AccessTokenLifetime=300, and BindTokensToSession=true

Other requests that match a different permit policy with no token-setting overrides inherit the API resource defaults and receive one-hour JWT access tokens.

When a request matches both policies, MonoCloud merges their settings using the restrictive merge rules. The resulting token is a 300-second, session-bound reference token.