SDK — define a customer role for a business account

POST

sdk

{environmentId}

businessAccounts

{businessAccountId}

roles

SDK — define a customer role for a business account

curl --request POST \
  --url https://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "role": "<string>",
  "autoExecute": true,
  "intent": {},
  "intentSignature": "<string>"
}
'

import requests

url = "https://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles"

payload = {
    "role": "<string>",
    "autoExecute": True,
    "intent": {},
    "intentSignature": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({role: '<string>', autoExecute: true, intent: {}, intentSignature: '<string>'})
};

fetch('https://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles', 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://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles",
  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([
    'role' => '<string>',
    'autoExecute' => true,
    'intent' => [
        
    ],
    'intentSignature' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles"

	payload := strings.NewReader("{\n  \"role\": \"<string>\",\n  \"autoExecute\": true,\n  \"intent\": {},\n  \"intentSignature\": \"<string>\"\n}")

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

	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://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"role\": \"<string>\",\n  \"autoExecute\": true,\n  \"intent\": {},\n  \"intentSignature\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"role\": \"<string>\",\n  \"autoExecute\": true,\n  \"intent\": {},\n  \"intentSignature\": \"<string>\"\n}"

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

{
  "version": 123
}

{
  "reason": "INTENT_REQUIRED",
  "intent": {},
  "message": "This proposal cannot be executed yet: addMember needs 1 more approval (1 of 2).",
  "proposalId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "approvalRequirements": [
    {
      "action": "addMember",
      "requirementId": "<string>",
      "required": 123,
      "approved": 123,
      "satisfied": true,
      "unmetMandatoryRoles": [
        "<string>"
      ]
    }
  ]
}

{
  "error": "<string>"
}

{
  "error": "No jwt provided!"
}

{
  "error": "Access Forbidden",
  "approvalRequirements": [
    {
      "action": "addMember",
      "requirementId": "<string>",
      "required": 123,
      "approved": 123,
      "satisfied": true,
      "unmetMandatoryRoles": [
        "<string>"
      ]
    }
  ]
}

{
  "error": "Not Found",
  "code": "not_found"
}

{
  "error": "Conflict: invalid state transition"
}

{
  "error": "Internal Server Error"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

environmentId

string

required

ID of the environment

Required string length: 36

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"95b11417-f18f-457f-8804-68e361f9164f"

businessAccountId

string

required

ID of the business account

Required string length: 36

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"95b11417-f18f-457f-8804-68e361f9164f"

Body

application/json

SDK defineRole body. A customer role always inherits a built-in one, which is what lets capability lookups and existing rules resolve through it.

role

string

required

Lowercase letters, numbers, hyphens and underscores.

inherits

enum<string>

required

Available options:

admin,

viewer

autoExecute

boolean

default:true

Whether the change applies the moment its quorum is met, or waits for an explicit execute. Read only on the first call, where it is stamped into the intent you sign; after that the signed intent is the authority. Defaults to true, because a change holding all its consent while waiting for a button press tends to be forgotten, and the deadline covers execution too.

intent

object

The initiator's proposal, signed with their session key. Built by the API, not the client — sign these exact bytes verbatim, because re-serializing can change them and invalidate the signature. autoExecute is inside the signed bytes, so an approver consents to it and nothing can flip it afterwards.

intentSignature

string

Response

Role defined; the new document version returned

The new version of the signed authorization document.

version

integer

required

Last modified on September 9, 2026

⌘I

SDK — define a customer role for a business account

curl --request POST \
  --url https://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "role": "<string>",
  "autoExecute": true,
  "intent": {},
  "intentSignature": "<string>"
}
'

import requests

url = "https://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles"

payload = {
    "role": "<string>",
    "autoExecute": True,
    "intent": {},
    "intentSignature": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({role: '<string>', autoExecute: true, intent: {}, intentSignature: '<string>'})
};

fetch('https://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles', 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://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles",
  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([
    'role' => '<string>',
    'autoExecute' => true,
    'intent' => [
        
    ],
    'intentSignature' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles"

	payload := strings.NewReader("{\n  \"role\": \"<string>\",\n  \"autoExecute\": true,\n  \"intent\": {},\n  \"intentSignature\": \"<string>\"\n}")

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

	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://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"role\": \"<string>\",\n  \"autoExecute\": true,\n  \"intent\": {},\n  \"intentSignature\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.dynamicauth.com/api/v0/sdk/{environmentId}/businessAccounts/{businessAccountId}/roles")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"role\": \"<string>\",\n  \"autoExecute\": true,\n  \"intent\": {},\n  \"intentSignature\": \"<string>\"\n}"

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

{
  "version": 123
}

{
  "reason": "INTENT_REQUIRED",
  "intent": {},
  "message": "This proposal cannot be executed yet: addMember needs 1 more approval (1 of 2).",
  "proposalId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "approvalRequirements": [
    {
      "action": "addMember",
      "requirementId": "<string>",
      "required": 123,
      "approved": 123,
      "satisfied": true,
      "unmetMandatoryRoles": [
        "<string>"
      ]
    }
  ]
}

{
  "error": "<string>"
}

{
  "error": "No jwt provided!"
}

{
  "error": "Access Forbidden",
  "approvalRequirements": [
    {
      "action": "addMember",
      "requirementId": "<string>",
      "required": 123,
      "approved": 123,
      "satisfied": true,
      "unmetMandatoryRoles": [
        "<string>"
      ]
    }
  ]
}

{
  "error": "Not Found",
  "code": "not_found"
}

{
  "error": "Conflict: invalid state transition"
}

{
  "error": "Internal Server Error"
}

Overview

Endpoints

Schemas

SDK — define a customer role for a business account

Authorizations

Path Parameters

Body

Response