Access

Roles, grants and class-level access control.

9 endpoints · Plakar Control Plane v0.18 · Base URL, authentication and errors

List the grants

GET /api/v1/account/organizations/{id}/access
Badge

Path parameters

  • id string<uuid> required
    Organization ID, at or below the caller’s.

Query parameters

  • offset integer
    Number of items to skip.
    Default: 0
  • limit integer
    Maximum number of items to return.
    Default: 100 Min: 1 Max: 100
  • search string
    Free-text search on grants.

Response 200 OK application/json

  • items array[object]
    • created_at string<date-time>
    • id string<uuid>
    • role object
      • category string
      • display_name string
      • name string
    • subject object
      • email string nullable
      • id string<uuid>
      • is_service boolean nullable
      • member_count integer nullable
      • name string
      • type string
  • total integer

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/account/organizations/{id}/access' \
  -H 'Authorization: Bearer <badge>'

Response 200

{
  "items": [
    {
      "created_at": "2026-01-01T00:00:00Z",
      "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
      "role": {
        "category": "string",
        "display_name": "string",
        "name": "string"
      },
      "subject": {
        "email": "string",
        "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
        "is_service": true,
        "member_count": 0,
        "name": "string",
        "type": "string"
      }
    }
  ],
  "total": 0
}

Create a grant

POST /api/v1/account/organizations/{id}/access
Badge

Path parameters

  • id string<uuid> required
    Organization ID, at or below the caller’s.

Request body application/json required

  • role_name string required
  • subject_id string<uuid>
  • subject_type string required

Response 200 OK application/json

  • created_at string<date-time>
  • id string<uuid>
  • role object
    • category string
    • display_name string
    • name string
  • subject object
    • email string nullable
    • id string<uuid>
    • is_service boolean nullable
    • member_count integer nullable
    • name string
    • type string

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X POST 'https://pcp.example.com/api/v1/account/organizations/{id}/access' \
  -H 'Authorization: Bearer <badge>' \
  -H 'Content-Type: application/json' \
  -d '{
  "role_name": "string",
  "subject_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "subject_type": "string"
}'

Response 200

{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "role": {
    "category": "string",
    "display_name": "string",
    "name": "string"
  },
  "subject": {
    "email": "string",
    "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "is_service": true,
    "member_count": 0,
    "name": "string",
    "type": "string"
  }
}

Get a grant

GET /api/v1/account/organizations/{id}/access/{grant_id}
Badge

Path parameters

  • id string<uuid> required
    Organization ID, at or below the caller’s.
  • grant_id string required

Response 200 OK application/json

  • created_at string<date-time>
  • id string<uuid>
  • role object
    • category string
    • display_name string
    • name string
  • subject object
    • email string nullable
    • id string<uuid>
    • is_service boolean nullable
    • member_count integer nullable
    • name string
    • type string

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/account/organizations/{id}/access/{grant_id}' \
  -H 'Authorization: Bearer <badge>'

Response 200

{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "role": {
    "category": "string",
    "display_name": "string",
    "name": "string"
  },
  "subject": {
    "email": "string",
    "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "is_service": true,
    "member_count": 0,
    "name": "string",
    "type": "string"
  }
}

Update a grant

PUT /api/v1/account/organizations/{id}/access/{grant_id}
Badge

Path parameters

  • id string<uuid> required
    Organization ID, at or below the caller’s.
  • grant_id string required

Request body application/json required

  • role_name string required
  • subject_id string<uuid>
  • subject_type string nullable

Response 200 OK application/json

  • created_at string<date-time>
  • id string<uuid>
  • role object
    • category string
    • display_name string
    • name string
  • subject object
    • email string nullable
    • id string<uuid>
    • is_service boolean nullable
    • member_count integer nullable
    • name string
    • type string

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X PUT 'https://pcp.example.com/api/v1/account/organizations/{id}/access/{grant_id}' \
  -H 'Authorization: Bearer <badge>' \
  -H 'Content-Type: application/json' \
  -d '{
  "role_name": "string",
  "subject_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "subject_type": "string"
}'

Response 200

{
  "created_at": "2026-01-01T00:00:00Z",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "role": {
    "category": "string",
    "display_name": "string",
    "name": "string"
  },
  "subject": {
    "email": "string",
    "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "is_service": true,
    "member_count": 0,
    "name": "string",
    "type": "string"
  }
}

Revoke a grant

DELETE /api/v1/account/organizations/{id}/access/{grant_id}
Badge

Path parameters

  • id string<uuid> required
    Organization ID, at or below the caller’s.
  • grant_id string required

Response 200 OK application/json

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X DELETE 'https://pcp.example.com/api/v1/account/organizations/{id}/access/{grant_id}' \
  -H 'Authorization: Bearer <badge>'

Response 200

{}

Get the access control of a class

GET /api/v1/account/organizations/{id}/classes/{subject}/access
Badge

Path parameters

  • id string<uuid> required
    Organization ID, at or below the caller’s.
  • subject string required

Response 200 OK application/json

  • can_execute array[string]
  • can_own array[string]
  • can_read array[string]
  • can_write array[string]

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/account/organizations/{id}/classes/{subject}/access' \
  -H 'Authorization: Bearer <badge>'

Response 200

{
  "can_execute": [
    "string"
  ],
  "can_own": [
    "string"
  ],
  "can_read": [
    "string"
  ],
  "can_write": [
    "string"
  ]
}

Set the access control of a class

PUT /api/v1/account/organizations/{id}/classes/{subject}/access
Badge

Path parameters

  • id string<uuid> required
    Organization ID, at or below the caller’s.
  • subject string required

Request body application/json required

  • assignments array[object]
    • group_ids array[string<uuid>] required
    • role string required
  • confirm_widen boolean

Response 200 OK application/json

  • can_execute array[string]
  • can_own array[string]
  • can_read array[string]
  • can_write array[string]

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X PUT 'https://pcp.example.com/api/v1/account/organizations/{id}/classes/{subject}/access' \
  -H 'Authorization: Bearer <badge>' \
  -H 'Content-Type: application/json' \
  -d '{
  "assignments": [
    {
      "group_ids": [
        "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
      ],
      "role": "string"
    }
  ],
  "confirm_widen": true
}'

Response 200

{
  "can_execute": [
    "string"
  ],
  "can_own": [
    "string"
  ],
  "can_read": [
    "string"
  ],
  "can_write": [
    "string"
  ]
}

List the roles

GET /api/v1/roles
Badge

Query parameters

  • category string
    Only roles of this category.
    Allowed: standard, advanced

Response 200 OK application/json

  • builtin boolean
  • category string
  • conflicts_with array[object] nullable
    • reason string nullable
    • role string
  • description string
  • display_name string
  • grants array[object]
    • access object
      • can_author boolean
      • can_delete boolean
      • can_execute boolean
      • can_view boolean
    • resource_type string
  • name string
  • rolls_up_to string nullable

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/roles' \
  -H 'Authorization: Bearer <badge>'

Response 200

[
  {
    "builtin": true,
    "category": "string",
    "conflicts_with": [
      {
        "reason": "string",
        "role": "string"
      }
    ],
    "description": "string",
    "display_name": "string",
    "grants": [
      {
        "access": {
          "can_author": true,
          "can_delete": true,
          "can_execute": true,
          "can_view": true
        },
        "resource_type": "string"
      }
    ],
    "name": "string",
    "rolls_up_to": "string"
  }
]

Get a role

GET /api/v1/roles/{role_name}
Badge

Path parameters

  • role_name string required

Response 200 OK application/json

  • builtin boolean
  • category string
  • conflicts_with array[object] nullable
    • reason string nullable
    • role string
  • description string
  • display_name string
  • grants array[object]
    • access object
      • can_author boolean
      • can_delete boolean
      • can_execute boolean
      • can_view boolean
    • resource_type string
  • name string
  • rolls_up_to string nullable

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/roles/{role_name}' \
  -H 'Authorization: Bearer <badge>'

Response 200

{
  "builtin": true,
  "category": "string",
  "conflicts_with": [
    {
      "reason": "string",
      "role": "string"
    }
  ],
  "description": "string",
  "display_name": "string",
  "grants": [
    {
      "access": {
        "can_author": true,
        "can_delete": true,
        "can_execute": true,
        "can_view": true
      },
      "resource_type": "string"
    }
  ],
  "name": "string",
  "rolls_up_to": "string"
}

Product

Integrations

Resources

Company

Newsletter