Create or update a policy

A policy is an authorization rule that controls which principals may perform which actions on matching resources. Policies connect identities to allowed operations on objects and other API resources.

Creates or replaces the policy identified by the policy query parameter. The request body defines the principals, actions, and objects patterns governed by the policy.

A successful request returns 204 No Content. Because "*" matches all values in a policy field, review broad patterns carefully; use Get a policy to inspect the saved definition or List policies to find identifiers.

If the request returns 400, verify the identifier and all three required arrays. For 401 or 403, check the x-api-key header and whether that key can manage policies.

POST
{{host}}/v1/policy?policy={{policy}}
VERB:POST
BASE URL:{{host}}/v1/policy
QUERY STRING:?policy={{policy}}

Query parameters#

  • policystring
    Required

    Unique identifier of the policy in the URL.

    example: all

Headers#

Send these headers with the request. Names are case-insensitive per HTTP rules.
  • x-api-keyRequired

    Your BigState API key.

    {{apiKey}}
  • Content-TypeRequired

    MIME type of the request body.

    application/json
  • AcceptRequired

    MIME types the client can understand in the response.

    application/json

Need a session token? See Token sign in.

Request body#

  • Allow all principals, actions, objects
    {

      "principals": [

        "*"

      ],

      "actions": [

        "*"

      ],

      "objects": [

        "*"

      ]

    }

Request parameters#

  • principalsarray[string]
    Required

    Principal patterns this policy applies to (e.g. `"*"` for all).

  • actionsarray[string]
    Required

    Allowed actions or patterns.

  • objectsarray[string]
    Required

    Object name patterns this policy governs.

Response parameters#

  • 204Response body · no content

    Policy was created or updated. No response body.

  • 401

    Unauthorized.

  • 403

    Access denied. The caller does not have sufficient rights to perform this operation.

  • 400Response body · object

    Bad request.

    {

      "error": 6,

      "desc": "Invalid request"

    }
    • errornumber

      Numeric error code. Use the response `desc` field for the human-readable explanation.

    • descstring

      Human-readable description of the error.

Examples#

Create or update a policy

Set principals, actions, and object patterns for a policy identifier. Success: 204, no body.

curl https://api.bigstate.dev/v1/policy?policy=all \

  --request POST \

  --header 'x-api-key: YOUR_API_KEY' \

  --header 'Content-Type: application/json' \

  --header 'Accept: application/json' \

  --data '{

  "principals": [

    "*"

  ],

  "actions": [

    "*"

  ],

  "objects": [

    "*"

  ]

}'
PolicyGet

© 2024 BigState