Regex URL Mapping Check

The Regex URL Mapping Permissions Check is a powerful feature that allows you to control access to your application's endpoints based on regular expressions for complex URL patterns. This feature supports two approaches:

Overview

Regex URL Mapping in Permit.io enables you to:

Define complex URL patterns using regular expressions to match dynamic and flexible URL structures
Extract multiple parameters from both URL paths and query strings using named capture groups
Match URLs with optional components, varying subdomains, or complex validation rules
Apply the same permission rules to multiple URL patterns that follow similar structures
Handle dynamic routing patterns that can't be easily expressed with simple path parameters
Support both HTTP and HTTPS protocols, and match across different domains or environments
Create flexible and maintainable access control rules that adapt to your API's URL structure

info

This feature is currently only available through the Permit.io API & PDP API.

Regex Pattern Basics

Regex URL mapping uses named capture groups (e.g., (?P<param_name>pattern)) to extract values from the URL. These captured values are automatically passed as attributes to your policy, making them available for ABAC (Attribute-Based Access Control) rules.

Setting Up Regex URL Mapping

Here's an example of creating a proxy configuration with a regex URL mapping rule:

curl --location 'https://api.permit.io/v2/facts/{project_id}/{env_id}/proxy_configs' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_PERMIT_KEY' \
--data '{
  "name": "Users API",
  "key": "users_api",
  "mapping_rules": [
    {
      "url": "^https://api\\.example\\.com/api/v1/users/(?P<user_id>[0-9]+)/profile$",
      "http_method": "post",
      "resource": "users",
      "action": "update",
      "url_type": "regex"
    }
  ],
  "secret":"abc123notUsed"
}'

danger

Noitce in the API call, the regex pattern is being sent as a JSON string. In JSON, backslashes need to be escaped themselves, so \. becomes \\. in the JSON payload.

Key points about this configuration:

The url_type must be set to "regex" to enable regex pattern matching
The regex pattern uses named capture groups (?P<name>pattern) to extract values
The pattern matches URLs that contain a numeric user ID in the path
The extracted user_id value will be available as an attribute in your policy

note

The secret value is still required for now, even though it isn't used. This will be fixed in a future relase of the proxy_configs API.

Checking Permissions

To use the URL Mapping Permissions Check, you must first start your PDP.

docker run -it \
  -p 7766:7000 \
  --env PDP_API_KEY=permit_key_{your_permit_env_key} \
  --env PDP_DEBUG=True \
  permitio/pdp-v2:latest

info

Simple URL mapping is supported in PDP version 0.8.0 or higher

Currently, checking permissions using URL Mapping is available through the endpoint /allowed_url on the PDP. The SDKs will be updated to support this feature soon.

Here's an example of a payload to localhost:7766/allowed_url (assuming you're running the PDP locally):

curl --location 'http://localhost:7766/allowed_url' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer permit_key_{your_key}' \
--data '{
  "user": {
    "key": "raz@permit.io"
  },
  "url": "https://api.example.com/users/123/profile",
  "http_method": "post",
  "tenant": "default"
}'

Common Regex Patterns

Basic Path Parameter

//JSON Escaped Regex URL
"url": "^https://api\\.example\\.com/users/(?P<user_id>[0-9]+)/profile$"

Matches

This pattern will match URLs with a numeric user ID in the path. It will match:

https://api.example.com/users/123/profile

https://api.example.com/users/456/profile

Pattern Part	Description
`^`	Matches the start of the string
`https://`	Matches the protocol literally
`api\.example\.com`	Matches the domain (dots are escaped with backslashes)
`/users/`	Matches the literal path segment
`(?P<user_id>[0-9]+)`	Named capture group: - `?P<user_id>`: Names the captured value "user_id" - `[0-9]+`: Matches one or more digits
`/profile`	Matches the literal path segment
`$`	Matches the end of the string

This pattern is perfect for RESTful APIs where you need to extract a numeric ID from a fixed URL structure.

Optional Path Component

//JSON Escaped Regex URL
"url": "^https://api\\.example\\.com/api/users(?:/(?P<user_id>[0-9]+))?$"

Matches

This pattern will match URLs with an optional user ID. It will match:

https://api.example.com/api/users

https://api.example.com/api/users/123

Pattern Part	Description
`^`	Matches the start of the string
`https://`	Matches the protocol literally
`api\.example\.com`	Matches the domain (dots are escaped with backslashes)
`/api/users`	Matches the literal path segments
`(?:...)`	Non-capturing group (used for grouping without capturing)
`(?P<user_id>[0-9]+)`	Named capture group: - `?P<user_id>`: Names the captured value "user_id" - `[0-9]+`: Matches one or more digits
`?`	Makes the entire group optional
`$`	Matches the end of the string

This pattern is useful when you have endpoints that can work both with and without an ID, like a list endpoint vs. a detail endpoint.

Multiple Query Parameters

//JSON Escaped Regex URL
"url": "^https://api\\.example\\.com/search\\?(?=.*q=(?P<query>[^&]+))(?=.*page=(?P<page>[0-9]+)).*$"

Matches

This pattern will match URLs with specific query parameters in any order. It will match:

https://api.example.com/search?q=test&page=1

https://api.example.com/search?page=2&q=example

Pattern Part	Description
`^`	Matches the start of the string
`https://`	Matches the protocol literally
`api\.example\.com`	Matches the domain (dots are escaped with backslashes)
`/search`	Matches the literal path segment
`\?`	Matches the literal question mark (escaped)
`(?=...)`	Positive lookahead (ensures something exists without consuming it)
`.*`	Matches any characters
`[^&]+`	Matches one or more characters that aren't ampersands (for query values)
`$`	Matches the end of the string

This pattern is ideal for search endpoints where parameters can appear in any order.

Subdomain Matching

//JSON Escaped Regex URL
"url": "^https://[\\w-]+\\.example\\.com/api/v1/users/(?P<user_id>[0-9]+)$"

Matches

This pattern will match URLs with any subdomain. It will match:

https://api.example.com/api/v1/users/123

https://staging.example.com/api/v1/users/456

https://dev-api.example.com/api/v1/users/789

Pattern Part	Description
`^`	Matches the start of the string
`https://`	Matches the protocol literally
`[\w-]+`	Matches one or more word characters or hyphens: - `\w`: matches letters, numbers, and underscores - `-`: allows hyphens in subdomains
`\.example\.com`	Matches the domain (dots are escaped with backslashes)
`/api/v1/users/`	Matches the literal path segments
`(?P<user_id>[0-9]+)`	Named capture group: - `?P<user_id>`: Names the captured value "user_id" - `[0-9]+`: Matches one or more digits
`$`	Matches the end of the string

This pattern is perfect for environments like staging, dev, or production APIs.

Flexible User Path Matching

//JSON Escaped Regex URL
"url": "^https?:\\/\\/[^\\/]+(?:.*?\\/users(?:\\/(?P<user_id>[^\\/]+))?(?:\\/.*)?)?$"

Matches

This pattern is useful for matching any URL that contains a user ID, regardless of the exact path structure. It will match URLs like:

https://api.example.com/users/123

https://api.example.com/v1/users/123

https://api.example.com/v1/users/123/profile

https://api.example.com/v1/users/123/settings/notifications

Pattern Part	Description
`^`	Matches the start of the string
`https?`	Matches "http" or "https" (the 's' is optional)
`:\/\/`	Matches the literal "://" (forward slashes are escaped)
`[^\/]+`	Matches the domain (any characters except forward slashes)
`.*?`	Non-greedy match of any characters
`(?:\/.*)?`	Optional trailing path segments
`$`	Matches the end of the string

This pattern is extremely flexible, matching any URL structure that contains a user ID, making it useful for complex API structures.

Protocol-Agnostic Matching

//JSON Escaped Regex URL
"url": "^https?:\\/\\/api\\.example\\.com\\/users\\/(?P<user_id>[0-9]+)\\/profile$"

Matches

This pattern will match both HTTP and HTTPS URLs. It will match:

http://api.example.com/users/123/profile

https://api.example.com/users/123/profile

Pattern Part	Description
`^`	Matches the start of the string
`https?`	Matches "http" or "https" (the 's' is optional)
`:\/\/`	Matches the literal "://" (forward slashes are escaped)
`api\.example\.com`	Matches the domain (dots are escaped)
`/users/`	Matches the literal path segment
`(?P<user_id>[0-9]+)`	Named capture group: - `?P<user_id>`: Names the captured value "user_id" - `[0-9]+`: Matches one or more digits
`/profile`	Matches the literal path segment
`$`	Matches the end of the string

This pattern is useful when your API needs to support both secure and non-secure connections, or during development when testing with different protocols.

Domain-Agnostic Matching

//JSON Escaped Regex URL
"url": "^https:\\/\\/[^\\/]+\\/api\\/v1\\/users\\/(?P<user_id>[0-9]+)\\/profile$"

Matches

This pattern will match any domain name. It will match:

https://api.example.com/api/v1/users/123/profile

https://api.staging.example.com/api/v1/users/123/profile

https://api.production.example.com/api/v1/users/123/profile

Pattern Part	Description
`^`	Matches the start of the string
`https:\/\/`	Matches the literal "https://" (forward slashes are escaped)
`[^\/]+`	Matches the domain (any characters except forward slashes)
`/api/v1/`	Matches the literal API version path
`/users/`	Matches the literal path segment
`(?P<user_id>[0-9]+)`	Named capture group: - `?P<user_id>`: Names the captured value "user_id" - `[0-9]+`: Matches one or more digits
`/profile`	Matches the literal path segment
`$`	Matches the end of the string

This pattern is ideal for microservices architectures where the same API might be deployed across different domains or environments, allowing you to reuse the same permission rules regardless of the domain.

Best Practices

Escape Special Characters: Always escape special characters in your regex patterns (e.g., \. for dots in domains).
Use Anchors: Start patterns with ^ and end with $ to ensure complete URL matching.
Named Groups: Always use named capture groups for parameters you want to extract.
Test Patterns: Test your regex patterns thoroughly before deploying to production.
Keep Patterns Simple: While regex is powerful, try to keep patterns as simple as possible for better maintainability.

Overview​

Regex Pattern Basics​

Setting Up Regex URL Mapping​

Checking Permissions​

Common Regex Patterns​

Basic Path Parameter​

Optional Path Component​

Multiple Query Parameters​

Subdomain Matching​

Flexible User Path Matching​

Protocol-Agnostic Matching​

Domain-Agnostic Matching​

Best Practices​

Contents

Overview

Regex Pattern Basics

Setting Up Regex URL Mapping

Checking Permissions

Common Regex Patterns

Basic Path Parameter

Optional Path Component

Multiple Query Parameters

Subdomain Matching

Flexible User Path Matching

Protocol-Agnostic Matching

Domain-Agnostic Matching

Best Practices