SutraID|Developer Docs
QuickstartAPI ReferenceDashboard

Policies

Attribute-based access control (ABAC) policies, password policies, and policy evaluation for fine-grained authorization.

POST/api/v1/organizations/:orgId/policiesCreate a policyBearer Token▾

Creates a new ABAC policy for an organization. Requires SUPER_ADMIN or ORG_ADMIN role.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization.e.g. org_01hx9z1q2w3e4r5t6y7u

Request Body

NameTypeRequiredDescription
namestringRequiredHuman-readable name for the policy.e.g. Allow API read access
descriptionstringOptionalOptional description of the policy purpose.e.g. Grants read-only access to all API resources.
effectstringOptionalWhether the policy allows or denies access. Defaults to ALLOW.e.g. ALLOW
ALLOWDENY
resourcestringRequiredThe resource pattern this policy applies to. Supports wildcards (e.g. "api:orders:*").e.g. api:orders:*
actionsstring[]RequiredList of actions this policy governs (e.g. ["read", "list"]). Use ["*"] for all actions.e.g. ["read", "list"]
conditionsobjectOptionalJSON object of contextual conditions (ipRange, geoLocations, timeWindow, or custom key-value pairs).e.g. { "ipRange": "10.0.0.0/8" }
prioritynumberOptionalEvaluation order priority. Higher values are evaluated first. Defaults to 0.e.g. 10
typestringOptionalPolicy type category.e.g. ACCESS
ACCESSSIGN_ONMFAPASSWORD
rulesarrayOptionalArray of rule objects for sign-on/auth policies. Each rule can specify conditions and requirements.e.g. [{ "priority": 1, "conditions": { "group": "Admins" }, "requirement": "MFA_REQUIRED" }]
enabledbooleanOptionalWhether the policy is active. Defaults to true.e.g. true

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique identifier of the created policy.
organizationIdstringOptionalOrganization the policy belongs to.
namestringOptionalName of the policy.
descriptionstring | nullOptionalDescription of the policy.
typestringOptionalPolicy type: ACCESS, SIGN_ON, MFA, or PASSWORD.
effectstringOptionalPolicy effect: ALLOW or DENY.
resourcestringOptionalResource pattern the policy applies to.
actionsstring[]OptionalActions governed by this policy.
rulesarrayOptionalArray of rule objects (for sign-on/auth policies).
conditionsobjectOptionalContextual conditions for policy evaluation.
prioritynumberOptionalEvaluation priority (higher = evaluated first).
enabledbooleanOptionalWhether the policy is active.
createdAtstringOptionalISO 8601 timestamp of when the policy was created.
updatedAtstringOptionalISO 8601 timestamp of the last update.

Response Example

{
  "id": "pol_01hx9z1q2w3e4r5t6y7u",
  "organizationId": "org_01hx9z1q2w3e4r5t6y7u",
  "name": "Allow API read access",
  "description": "Grants read-only access to all API resources.",
  "type": "ACCESS",
  "effect": "ALLOW",
  "resource": "api:orders:*",
  "actions": [
    "read",
    "list"
  ],
  "rules": [],
  "conditions": {
    "ipRange": "10.0.0.0/8"
  },
  "priority": 10,
  "enabled": true,
  "createdAt": "2024-06-15T10:00:00Z",
  "updatedAt": "2024-06-15T10:00:00Z"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/organizations/org_01hx9z1q2w3e4r5t6y7u/policies" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Allow API read access",
    "description": "Grants read-only access to all API resources.",
    "effect": "ALLOW",
    "resource": "api:orders:*",
    "actions": ["read", "list"],
    "conditions": { "ipRange": "10.0.0.0/8" },
    "priority": 10,
    "type": "ACCESS",
    "enabled": true
  }'
GET/api/v1/organizations/:orgId/policiesList policiesBearer Token▾

Returns all policies for an organization, ordered by priority (descending) then creation date. Optionally filter by policy type. Requires SUPER_ADMIN, ORG_ADMIN, or READ_ONLY_ADMIN role.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization.e.g. org_01hx9z1q2w3e4r5t6y7u
typestringOptionalFilter policies by type.e.g. ACCESS
ACCESSSIGN_ONMFAPASSWORD

Response Fields

NameTypeRequiredDescription
[]Policy[]OptionalArray of policy objects.
[].idstringOptionalUnique identifier of the policy.
[].organizationIdstringOptionalOrganization the policy belongs to.
[].namestringOptionalName of the policy.
[].descriptionstring | nullOptionalDescription of the policy.
[].typestringOptionalPolicy type: ACCESS, SIGN_ON, MFA, or PASSWORD.
[].effectstringOptionalPolicy effect: ALLOW or DENY.
[].resourcestringOptionalResource pattern the policy applies to.
[].actionsstring[]OptionalActions governed by this policy.
[].rulesarrayOptionalArray of rule objects (for sign-on/auth policies).
[].conditionsobjectOptionalContextual conditions for policy evaluation.
[].prioritynumberOptionalEvaluation priority (higher = evaluated first).
[].enabledbooleanOptionalWhether the policy is active.
[].createdAtstringOptionalISO 8601 timestamp of when the policy was created.
[].updatedAtstringOptionalISO 8601 timestamp of the last update.

Response Example

{
  "data": [
    {
      "id": "pol_01hx9z1q2w3e4r5t6y7u",
      "organizationId": "org_01hx9z1q2w3e4r5t6y7u",
      "name": "Allow API read access",
      "description": "Grants read-only access to all API resources.",
      "type": "ACCESS",
      "effect": "ALLOW",
      "resource": "api:orders:*",
      "actions": [
        "read",
        "list"
      ],
      "rules": [],
      "conditions": {
        "ipRange": "10.0.0.0/8"
      },
      "priority": 10,
      "enabled": true,
      "createdAt": "2024-06-15T10:00:00Z",
      "updatedAt": "2024-06-15T10:00:00Z"
    },
    {
      "id": "pol_02jy0a2r3x4f5s6u7v8w",
      "organizationId": "org_01hx9z1q2w3e4r5t6y7u",
      "name": "Default Sign-on Policy",
      "description": "Default authentication rules for all users",
      "type": "SIGN_ON",
      "effect": "ALLOW",
      "resource": "auth:login",
      "actions": [
        "login"
      ],
      "rules": [
        {
          "id": "default_rule",
          "name": "Catch-all",
          "conditions": {
            "group": "Everyone"
          },
          "requirement": "MFA_OPTIONAL",
          "priority": 999
        }
      ],
      "conditions": {},
      "priority": 0,
      "enabled": true,
      "createdAt": "2024-06-10T08:00:00Z",
      "updatedAt": "2024-06-10T08:00:00Z"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/organizations/org_01hx9z1q2w3e4r5t6y7u/policies?type=ACCESS" \
  -H "Authorization: Bearer <your_token>"
GET/api/v1/organizations/:orgId/policies/:policyIdGet a policyBearer Token▾

Retrieves a single policy by its ID. Requires SUPER_ADMIN, ORG_ADMIN, or READ_ONLY_ADMIN role.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization.e.g. org_01hx9z1q2w3e4r5t6y7u
policyIdstring (UUID)RequiredUnique identifier of the policy.e.g. pol_01hx9z1q2w3e4r5t6y7u

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique identifier of the policy.
organizationIdstringOptionalOrganization the policy belongs to.
namestringOptionalName of the policy.
descriptionstring | nullOptionalDescription of the policy.
typestringOptionalPolicy type: ACCESS, SIGN_ON, MFA, or PASSWORD.
effectstringOptionalPolicy effect: ALLOW or DENY.
resourcestringOptionalResource pattern the policy applies to.
actionsstring[]OptionalActions governed by this policy.
rulesarrayOptionalArray of rule objects (for sign-on/auth policies).
conditionsobjectOptionalContextual conditions for policy evaluation.
prioritynumberOptionalEvaluation priority (higher = evaluated first).
enabledbooleanOptionalWhether the policy is active.
createdAtstringOptionalISO 8601 timestamp of when the policy was created.
updatedAtstringOptionalISO 8601 timestamp of the last update.

Response Example

{
  "id": "pol_01hx9z1q2w3e4r5t6y7u",
  "organizationId": "org_01hx9z1q2w3e4r5t6y7u",
  "name": "Allow API read access",
  "description": "Grants read-only access to all API resources.",
  "type": "ACCESS",
  "effect": "ALLOW",
  "resource": "api:orders:*",
  "actions": [
    "read",
    "list"
  ],
  "rules": [],
  "conditions": {
    "ipRange": "10.0.0.0/8"
  },
  "priority": 10,
  "enabled": true,
  "createdAt": "2024-06-15T10:00:00Z",
  "updatedAt": "2024-06-15T10:00:00Z"
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/organizations/org_01hx9z1q2w3e4r5t6y7u/policies/pol_01hx9z1q2w3e4r5t6y7u" \
  -H "Authorization: Bearer <your_token>"
PUT/api/v1/organizations/:orgId/policies/:policyIdUpdate a policyBearer Token▾

Updates an existing ABAC policy. All body fields are optional; only provided fields are changed. Requires SUPER_ADMIN or ORG_ADMIN role.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization.e.g. org_01hx9z1q2w3e4r5t6y7u
policyIdstring (UUID)RequiredUnique identifier of the policy to update.e.g. pol_01hx9z1q2w3e4r5t6y7u

Request Body

NameTypeRequiredDescription
namestringOptionalUpdated name for the policy.e.g. Allow API full access
descriptionstringOptionalUpdated description.e.g. Grants full access to all API resources.
effectstringOptionalUpdated effect.e.g. ALLOW
ALLOWDENY
resourcestringOptionalUpdated resource pattern.e.g. api:*
actionsstring[]OptionalUpdated list of actions.e.g. ["read", "write", "delete"]
conditionsobjectOptionalUpdated contextual conditions.e.g. { "ipRange": "192.168.0.0/16" }
prioritynumberOptionalUpdated evaluation priority.e.g. 20
enabledbooleanOptionalEnable or disable the policy.e.g. true

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique identifier of the policy.
organizationIdstringOptionalOrganization the policy belongs to.
namestringOptionalUpdated name of the policy.
descriptionstring | nullOptionalUpdated description.
typestringOptionalPolicy type: ACCESS, SIGN_ON, MFA, or PASSWORD.
effectstringOptionalPolicy effect: ALLOW or DENY.
resourcestringOptionalResource pattern the policy applies to.
actionsstring[]OptionalActions governed by this policy.
rulesarrayOptionalArray of rule objects (for sign-on/auth policies).
conditionsobjectOptionalContextual conditions for policy evaluation.
prioritynumberOptionalEvaluation priority.
enabledbooleanOptionalWhether the policy is active.
createdAtstringOptionalISO 8601 timestamp of when the policy was created.
updatedAtstringOptionalISO 8601 timestamp of the last update.

Response Example

{
  "id": "pol_01hx9z1q2w3e4r5t6y7u",
  "organizationId": "org_01hx9z1q2w3e4r5t6y7u",
  "name": "Allow API full access",
  "description": "Grants full access to all API resources.",
  "type": "ACCESS",
  "effect": "ALLOW",
  "resource": "api:*",
  "actions": [
    "read",
    "write",
    "delete"
  ],
  "rules": [],
  "conditions": {
    "ipRange": "192.168.0.0/16"
  },
  "priority": 20,
  "enabled": true,
  "createdAt": "2024-06-15T10:00:00Z",
  "updatedAt": "2024-06-15T14:30:00Z"
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/organizations/org_01hx9z1q2w3e4r5t6y7u/policies/pol_01hx9z1q2w3e4r5t6y7u" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Allow API full access",
    "actions": ["read", "write", "delete"],
    "resource": "api:*",
    "priority": 20
  }'
DELETE/api/v1/organizations/:orgId/policies/:policyIdDelete a policyBearer Token▾

Permanently deletes a policy. This action cannot be undone. Requires SUPER_ADMIN or ORG_ADMIN role.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization.e.g. org_01hx9z1q2w3e4r5t6y7u
policyIdstring (UUID)RequiredUnique identifier of the policy to delete.e.g. pol_01hx9z1q2w3e4r5t6y7u

Response Fields

NameTypeRequiredDescription
messagestringOptionalConfirmation message indicating the policy was deleted.

Response Example

{
  "message": "Policy deleted successfully"
}

Code Examples

curl -X DELETE "https://api.sutraid.com/api/v1/organizations/org_01hx9z1q2w3e4r5t6y7u/policies/pol_01hx9z1q2w3e4r5t6y7u" \
  -H "Authorization: Bearer <your_token>"
GET/api/v1/organizations/:orgId/policies/passwordGet password policyBearer Token▾

Retrieves the password complexity and lockout policy for an organization. A default policy is auto-created if none exists. Requires SUPER_ADMIN, ORG_ADMIN, or READ_ONLY_ADMIN role.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization.e.g. org_01hx9z1q2w3e4r5t6y7u

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique identifier of the password policy.
organizationIdstringOptionalOrganization the policy belongs to.
minLengthnumberOptionalMinimum password length.
requireUppercasebooleanOptionalWhether uppercase letters are required.
requireLowercasebooleanOptionalWhether lowercase letters are required.
requireNumbersbooleanOptionalWhether numeric digits are required.
requireSymbolsbooleanOptionalWhether special characters are required.
maxAgeDaysnumberOptionalMaximum password age in days. 0 means passwords never expire.
historyCountnumberOptionalNumber of previous passwords that cannot be reused.
lockoutThresholdnumberOptionalNumber of failed attempts before account lockout.
lockoutDurationnumberOptionalLockout duration in minutes.
createdAtstringOptionalISO 8601 timestamp of when the policy was created.
updatedAtstringOptionalISO 8601 timestamp of the last update.

Response Example

{
  "id": "pwp_01hx9z1q2w3e4r5t6y7u",
  "organizationId": "org_01hx9z1q2w3e4r5t6y7u",
  "minLength": 12,
  "requireUppercase": true,
  "requireLowercase": true,
  "requireNumbers": true,
  "requireSymbols": true,
  "maxAgeDays": 0,
  "historyCount": 5,
  "lockoutThreshold": 5,
  "lockoutDuration": 30,
  "createdAt": "2024-06-01T08:00:00Z",
  "updatedAt": "2024-06-01T08:00:00Z"
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/organizations/org_01hx9z1q2w3e4r5t6y7u/policies/password" \
  -H "Authorization: Bearer <your_token>"
PUT/api/v1/organizations/:orgId/policies/passwordUpdate password policyBearer Token▾

Updates the password complexity and lockout policy for an organization. All body fields are optional. Requires SUPER_ADMIN or ORG_ADMIN role.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization.e.g. org_01hx9z1q2w3e4r5t6y7u

Request Body

NameTypeRequiredDescription
minLengthnumberOptionalMinimum password length.e.g. 14
requireUppercasebooleanOptionalWhether uppercase letters are required.e.g. true
requireLowercasebooleanOptionalWhether lowercase letters are required.e.g. true
requireNumbersbooleanOptionalWhether numeric digits are required.e.g. true
requireSymbolsbooleanOptionalWhether special characters are required.e.g. true
lockoutThresholdnumberOptionalNumber of failed login attempts before account lockout.e.g. 3
lockoutDurationnumberOptionalLockout duration in minutes.e.g. 60

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique identifier of the password policy.
organizationIdstringOptionalOrganization the policy belongs to.
minLengthnumberOptionalMinimum password length.
requireUppercasebooleanOptionalWhether uppercase letters are required.
requireLowercasebooleanOptionalWhether lowercase letters are required.
requireNumbersbooleanOptionalWhether numeric digits are required.
requireSymbolsbooleanOptionalWhether special characters are required.
maxAgeDaysnumberOptionalMaximum password age in days.
historyCountnumberOptionalNumber of previous passwords that cannot be reused.
lockoutThresholdnumberOptionalNumber of failed attempts before lockout.
lockoutDurationnumberOptionalLockout duration in minutes.
createdAtstringOptionalISO 8601 timestamp of when the policy was created.
updatedAtstringOptionalISO 8601 timestamp of the last update.

Response Example

{
  "id": "pwp_01hx9z1q2w3e4r5t6y7u",
  "organizationId": "org_01hx9z1q2w3e4r5t6y7u",
  "minLength": 14,
  "requireUppercase": true,
  "requireLowercase": true,
  "requireNumbers": true,
  "requireSymbols": true,
  "maxAgeDays": 0,
  "historyCount": 5,
  "lockoutThreshold": 3,
  "lockoutDuration": 60,
  "createdAt": "2024-06-01T08:00:00Z",
  "updatedAt": "2024-06-20T11:45:00Z"
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/organizations/org_01hx9z1q2w3e4r5t6y7u/policies/password" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "minLength": 14,
    "lockoutThreshold": 3,
    "lockoutDuration": 60
  }'
POST/api/v1/organizations/:orgId/policies/evaluateEvaluate policiesBearer Token▾

Tests policy evaluation for a given resource, action, and context. Uses deny-override strategy: if any DENY policy matches, the result is DENY. Returns the decision, the matched policy, and the reason. Requires SUPER_ADMIN or ORG_ADMIN role.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization.e.g. org_01hx9z1q2w3e4r5t6y7u

Request Body

NameTypeRequiredDescription
userIdstringOptionalUser ID to evaluate policies for. Defaults to the authenticated user.e.g. usr_01hx9z1q2w3e4r5t6y7u
agentIdstringOptionalAgent/service ID making the request (for machine-to-machine evaluation).e.g. agent_01hx9z1q2w3e4r5t6y7u
resourcestringRequiredThe resource to evaluate access for.e.g. api:orders:123
actionstringRequiredThe action to evaluate (e.g. "read", "write", "delete").e.g. read
contextobjectOptionalAdditional context for condition matching (ipAddress, userAgent, geoLocation, timestamp, or custom keys).e.g. { "ipAddress": "10.0.1.50", "geoLocation": "US" }

Response Fields

NameTypeRequiredDescription
decisionstringOptionalThe evaluation result: ALLOW or DENY.
matchedPolicyobject | undefinedOptionalThe policy that produced the decision (absent if no policy matched).
matchedPolicy.idstringOptionalID of the matched policy.
matchedPolicy.namestringOptionalName of the matched policy.
matchedPolicy.effectstringOptionalEffect of the matched policy: ALLOW or DENY.
matchedPolicy.prioritynumberOptionalPriority of the matched policy.
reasonstringOptionalHuman-readable explanation of the decision.

Response Example

{
  "decision": "ALLOW",
  "matchedPolicy": {
    "id": "pol_01hx9z1q2w3e4r5t6y7u",
    "name": "Allow API read access",
    "effect": "ALLOW",
    "priority": 10
  },
  "reason": "Allowed by policy: Allow API read access"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/organizations/org_01hx9z1q2w3e4r5t6y7u/policies/evaluate" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "api:orders:123",
    "action": "read",
    "context": {
      "ipAddress": "10.0.1.50",
      "geoLocation": "US"
    }
  }'