diff --git a/docs/documentation/platform/access-controls/attribute-based-access-controls.mdx b/docs/documentation/platform/access-controls/attribute-based-access-controls.mdx
new file mode 100644
index 000000000..42a32d6b8
--- /dev/null
+++ b/docs/documentation/platform/access-controls/attribute-based-access-controls.mdx
@@ -0,0 +1,65 @@
+---
+title: "Attribute-based Access Controls"
+description: "Learn how to use ABAC to manage permissions based on identity attributes."
+---
+
+Infisical's Attribute-based Access Controls (ABAC) allow for dynamic, attribute-driven permissions for both user and machine identities.
+ABAC policies use metadata attributes—stored as key-value pairs on identities—to enforce fine-grained permissions that are context aware.
+
+In ABAC, access controls are defined using metadata attributes, such as location or department, which can be set directly on user or machine identities.
+During policy execution, these attributes are evaluated, and determine whether said actor can access the requested resource or perform the requested operation.
+
+## Project-level Permissions
+
+Attribute-based access controls are currently available for polices defined on projects. You can set ABAC permissions to control access to environments, folders, secrets, and secret tags.
+
+### Setting Metadata on Identities
+
+
+
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+
+
+ For organizations using SAML for login, Infisical automatically maps metadata attributes from SAML assertions to user identities.
+ This makes it easy to create policies that dynamically adapt based on the SAML user’s attributes.
+
+
+
+
+## Defining ABAC Policies
+
+
+
+ABAC policies make use of identity metadata to define dynamic permissions. Each attribute must start and end with double curly-brackets `{{ }}`.
+The following attributes are available within project permissions:
+
+- **User ID**: `{{ identity.id }}`
+- **Username**: `{{ identity.username }}`
+- **Metadata Attributes**: `{{ identity.metadata. }}`
+
+During policy execution, these placeholders are replaced by their actual values prior to evaluation.
+
+### Example Use Case
+
+#### Location-based Access Control
+
+Suppose you want to restrict access to secrets within a specific folder based on a user's geographic region.
+You could assign a `location` attribute to each user (e.g., `identity.metadata.location`).
+You could then structure your folders to align with this attribute and define permissions accordingly.
+
+For example, a policy might restrict access to folders matching the user's location attribute in the following pattern:
+```
+/appA/{{ identity.metadata.location }}
+```
+Using this structure, users can only access folders that correspond to their configured `location` attribute.
+Consequently, if a users attribute changes due to relocation, no policies need to be changed to gain access to the folders associated with their new location.
diff --git a/docs/documentation/platform/access-controls/overview.mdx b/docs/documentation/platform/access-controls/overview.mdx
index 54fc8ff25..552117c7e 100644
--- a/docs/documentation/platform/access-controls/overview.mdx
+++ b/docs/documentation/platform/access-controls/overview.mdx
@@ -15,6 +15,15 @@ To make sure that users and machine identities are only accessing the resources
>
Manage user and machine identitity permissions through predefined roles.
+
+
+ Manage user and machine identitity permissions based on their attributes.
+