Create a PermissionAssignment

curl --request POST \
  --url https://api.checkfu.com/v1/permission-assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "subject": {
    "kind": "principal",
    "principal": "<string>"
  },
  "resource": {
    "id": "<string>"
  },
  "expires_at": "<string>",
  "valid_from": "<string>",
  "rationale": "<string>"
}
'

import requests

url = "https://api.checkfu.com/v1/permission-assignments"

payload = {
    "subject": {
        "kind": "principal",
        "principal": "<string>"
    },
    "resource": { "id": "<string>" },
    "expires_at": "<string>",
    "valid_from": "<string>",
    "rationale": "<string>"
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {kind: 'principal', principal: '<string>'},
    resource: {id: '<string>'},
    expires_at: '<string>',
    valid_from: '<string>',
    rationale: '<string>'
  })
};

fetch('https://api.checkfu.com/v1/permission-assignments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/permission-assignments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subject' => [
        'kind' => 'principal',
        'principal' => '<string>'
    ],
    'resource' => [
        'id' => '<string>'
    ],
    'expires_at' => '<string>',
    'valid_from' => '<string>',
    'rationale' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/permission-assignments"

	payload := strings.NewReader("{\n  \"subject\": {\n    \"kind\": \"principal\",\n    \"principal\": \"<string>\"\n  },\n  \"resource\": {\n    \"id\": \"<string>\"\n  },\n  \"expires_at\": \"<string>\",\n  \"valid_from\": \"<string>\",\n  \"rationale\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/permission-assignments")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subject\": {\n    \"kind\": \"principal\",\n    \"principal\": \"<string>\"\n  },\n  \"resource\": {\n    \"id\": \"<string>\"\n  },\n  \"expires_at\": \"<string>\",\n  \"valid_from\": \"<string>\",\n  \"rationale\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/permission-assignments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subject\": {\n    \"kind\": \"principal\",\n    \"principal\": \"<string>\"\n  },\n  \"resource\": {\n    \"id\": \"<string>\"\n  },\n  \"expires_at\": \"<string>\",\n  \"valid_from\": \"<string>\",\n  \"rationale\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "subject": {
    "kind": "principal",
    "principal": "<string>"
  },
  "resource": {
    "kind": "agent-definition",
    "id": "<string>"
  },
  "permission": "read",
  "resource_version": 1,
  "created_at": "<string>",
  "updated_at": "<string>",
  "expires_at": "<string>",
  "valid_from": "<string>",
  "rationale": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Create a PermissionAssignment

Create one immutable PermissionAssignment binding a subject (principal, group, agent definition, agent installation, surface scope, or session) to one enumerated resource and one permission. Each resource kind admits only its own permissions, so an impossible pairing is rejected rather than stored. Bounds require canonical UTC timestamps with exactly three fractional digits. PermissionAssignments are never patched: delete and recreate to change one. Accepts an Idempotency-Key.

Checkfu support posture: alpha; hosted. Required evidence journey: governance-registry. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST

permission-assignments

curl --request POST \
  --url https://api.checkfu.com/v1/permission-assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "subject": {
    "kind": "principal",
    "principal": "<string>"
  },
  "resource": {
    "id": "<string>"
  },
  "expires_at": "<string>",
  "valid_from": "<string>",
  "rationale": "<string>"
}
'

import requests

url = "https://api.checkfu.com/v1/permission-assignments"

payload = {
    "subject": {
        "kind": "principal",
        "principal": "<string>"
    },
    "resource": { "id": "<string>" },
    "expires_at": "<string>",
    "valid_from": "<string>",
    "rationale": "<string>"
}
headers = {
    "checkfu-version": "<checkfu-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {kind: 'principal', principal: '<string>'},
    resource: {id: '<string>'},
    expires_at: '<string>',
    valid_from: '<string>',
    rationale: '<string>'
  })
};

fetch('https://api.checkfu.com/v1/permission-assignments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/permission-assignments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'subject' => [
        'kind' => 'principal',
        'principal' => '<string>'
    ],
    'resource' => [
        'id' => '<string>'
    ],
    'expires_at' => '<string>',
    'valid_from' => '<string>',
    'rationale' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/permission-assignments"

	payload := strings.NewReader("{\n  \"subject\": {\n    \"kind\": \"principal\",\n    \"principal\": \"<string>\"\n  },\n  \"resource\": {\n    \"id\": \"<string>\"\n  },\n  \"expires_at\": \"<string>\",\n  \"valid_from\": \"<string>\",\n  \"rationale\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/permission-assignments")
  .header("checkfu-version", "<checkfu-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subject\": {\n    \"kind\": \"principal\",\n    \"principal\": \"<string>\"\n  },\n  \"resource\": {\n    \"id\": \"<string>\"\n  },\n  \"expires_at\": \"<string>\",\n  \"valid_from\": \"<string>\",\n  \"rationale\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/permission-assignments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subject\": {\n    \"kind\": \"principal\",\n    \"principal\": \"<string>\"\n  },\n  \"resource\": {\n    \"id\": \"<string>\"\n  },\n  \"expires_at\": \"<string>\",\n  \"valid_from\": \"<string>\",\n  \"rationale\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "subject": {
    "kind": "principal",
    "principal": "<string>"
  },
  "resource": {
    "kind": "agent-definition",
    "id": "<string>"
  },
  "permission": "read",
  "resource_version": 1,
  "created_at": "<string>",
  "updated_at": "<string>",
  "expires_at": "<string>",
  "valid_from": "<string>",
  "rationale": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version

enum<string>

required

Available options:

2026-08-27

idempotency-key

string

Maximum string length: 255

Body

application/json

subject

object

required

Show child attributes

resource

object

required

Show child attributes

permission

enum<string>

required

Available options:

read,

write,

use,

invoke,

steer,

observe,

approve,

edit,

view,

act_as,

use_agent,

use_connection,

use_tool,

use_memory,

use_model,

use_harness,

use_environment,

publish_artifact,

create_routine,

manage_routine

expires_at

string

A retained audit timestamp using the historical zero-to-three fractional-digit encoding.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$

valid_from

string

A retained audit timestamp using the historical zero-to-three fractional-digit encoding.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$

rationale

string

Required string length: 1 - 512

Response

Success

string

required

Pattern: ^perm_[0-9a-f]{32}$

subject

object

required

Show child attributes

resource

object

required

Show child attributes

permission

enum<string>

required

Available options:

read,

write,

use,

invoke,

steer,

observe,

approve,

edit,

view,

act_as,

use_agent,

use_connection,

use_tool,

use_memory,

use_model,

use_harness,

use_environment,

publish_artifact,

create_routine,

manage_routine

resource_version

integer

required

Required range: x > 0

created_at

string

required

updated_at

string

required

expires_at

string

A retained audit timestamp using the historical zero-to-three fractional-digit encoding.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$

valid_from

string

A retained audit timestamp using the historical zero-to-three fractional-digit encoding.

Maximum string length: 24

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$

rationale

string

Required string length: 1 - 512

Developer tools

Canonical tables

Author protocols

Generated HTTP API

Create a PermissionAssignment

Authorizations

Headers

Body

Response