Skip to main content

​
POST /v1beta1/policies

Create a new policy that assigns a specific role to a principal (user or group) on a resource (organization, project, etc.).

​
Request Body

​
body
object
required
Policy creation details.
​
role_id
string
required
ID of the role to assign. Must be a valid role ID.
​
resource
string
required
Resource identifier in the format namespace:resource_id.Examples:
  • app/organization:org-123 - Organization resource
  • app/project:proj-456 - Project resource
  • app/group:group-789 - Group resource
​
principal
string
required
Principal identifier in the format namespace:principal_id.Examples:
  • app/user:user-123 - User principal
  • app/group:group-456 - Group principal
  • app/serviceuser:sa-789 - Service account principal
​
title
string
Optional human-readable title for the policy.
​
metadata
object
Optional metadata to associate with the policy. Can contain arbitrary key-value pairs.

​
Response

​
policy
object
The newly created policy object.
​
id
string
Unique identifier for the created policy.
​
role_id
string
ID of the role assigned by this policy.
​
resource
string
Resource identifier in the format namespace:resource_id.
​
principal
string
Principal identifier in the format namespace:principal_id.
​
metadata
object
Metadata associated with the policy.
​
created_at
timestamp
Timestamp when the policy was created.
​
updated_at
timestamp
Timestamp when the policy was last updated.
curl -X POST 'https://api.frontier.example.com/v1beta1/policies' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "body": {
      "role_id": "admin-role-id",
      "resource": "app/organization:org-123",
      "principal": "app/user:user-456",
      "metadata": {
        "description": "Admin access to organization"
      }
    }
  }'

​
Response Example

{
  "policy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "role_id": "admin-role-id",
    "resource": "app/organization:org-123",
    "principal": "app/user:user-456",
    "metadata": {
      "description": "Admin access to organization"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Error Responses

​
error
object
​
code
string
Error code. Possible values:
  • invalid_argument - Invalid request parameters (invalid role ID, malformed namespace notation, or invalid policy details)
  • internal - Internal server error
​
message
string
Human-readable error message.

​
Notes

  • The resource and principal must use the namespace:resource_id format (e.g., app/organization:org-id)
  • The role ID must exist and be valid
  • Creating a policy generates an audit event (policy.created)
  • Policies define access control by linking principals (who), resources (what), and roles (permissions)

Build docs developers (and LLMs) love

Get started for freeTalk to us