Get 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.

Returns the policy identified by the policy query parameter. The response contains policy and a nested definition with principals, actions, and objects, matching each record returned by List policies.

Use Create or update a policy to create a missing policy or replace its definition. A successful lookup returns 200 OK; an unknown identifier returns 404.

If the request returns 400, verify the query parameter. For 401 or 403, check the x-api-key header and the key's access to the policy.

GET

{{host}}/v1/policy?policy={{policy}}

VERB:GET

BASE URL:{{host}}/v1/policy

QUERY STRING:?policy={{policy}}

Query parameters#

RequiredOptional

policystring
Required
Unique identifier of the policy in the URL.
example: all

Headers#

RequiredOptional

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.

Response parameters#

200Response body · object
Current policy: identifier plus a `definition` object with principals, actions, and objects.
- policystring
  Unique identifier of this policy.
  example: all
- definitionobject
  Rule lists: principals, actions, and objects.
  - definition.principalsarray[string]
    Principal patterns this policy applies to (e.g. `"*"` for all).
  - definition.actionsarray[string]
    Allowed actions or patterns.
  - definition.objectsarray[string]
    Object name patterns this policy governs.
401
Unauthorized.
403
Access denied. The caller does not have sufficient rights to perform this operation.
404
No policy exists for the given identifier.
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#

Get a policy

Fetch `policy` id and `definition` (principals, actions, objects) by identifier.


curl https://api.bigstate.dev/v1/policy?policy=all \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json'

Create or update Delete

Description
Query parameters
Headers
Response parameters
Examples