Skip to content
Documentation
Tutorials
8.5. Policy Management

8.5. Policy Management

This tutorial covers the Policy Management system in the dAIEDGE Middleware, enabling fine-grained access control using ODRL (Open Digital Rights Language) policies.

Overview

Policies allow you to:

  • Define usage constraints for hardware resources
  • Control who can access specific services (benchmarking types)
  • Require specific Verifiable Credential claims for access
  • Manage access at both user (DID) and hardware levels

What are ODRL Policies?

ODRL is a W3C standard for expressing permissions, prohibitions, and obligations. In dAIEDGE:

  • DID Policies: Define what services a user identity can access
  • Hardware Policies: Define what services a hardware resource can provide

Prerequisites

Required Role

All write operations (create, edit, delete) require the LICENSE_MANAGER_ROLE:

OperationRequired Role
Get DID PolicyOwner of the DID
Get Hardware PolicyOwner of the hardware
Create/Edit/Delete DID PolicyLICENSE_MANAGER_ROLE
Create/Edit/Delete Hardware PolicyLICENSE_MANAGER_ROLE

Policy Structure

Policies follow the ODRL specification with dAIEDGE-specific extensions:

{
  "@context": [
    "http://www.w3.org/ns/odrl.jsonld",
    {
      "vlab": "http://vlab.example.org/ns#"
    }
  ],
  "uid": "urn:vlab:policy:user:did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "type": "Set",
  "assigner": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "profile": "http://vlab.example.org/odrl-profile",
  "permission": [
    {
      "target": "http://vlab.example.org/platform/all",
      "action": [
        {
          "type": "vlab:allowService",
          "refinement": {
            "type": "vlab:serviceType",
            "value": "TYPE1"
          }
        }
      ],
      "constraint": [
        {
          "leftOperand": "vlab:vcClaim",
          "operator": "eq",
          "rightOperand": "Group1",
          "vlab:vcType": "vlab:CertifiedBenchmarker",
          "vlab:vcPath": "$.credentialSubject.group"
        }
      ]
    }
  ]
}

Key Fields

FieldDescription
@contextODRL and vLab vocabulary namespaces
uidUnique policy identifier (must match resource)
typePolicy type (always “Set”)
assignerDID of the policy issuer
profilePolicy profile
permissionArray of permission rules

Permission Structure

FieldDescription
targetResource the permission applies to
actionArray of allowed actions
constraintOptional conditions (e.g., VC claims) for user policies

Constraint Fields (User Policies)

FieldDescription
leftOperandThe operand to evaluate (e.g., vlab:vcClaim)
operatorComparison operator (eq or neq)
rightOperandValue to compare against (e.g., Group1)
vlab:vcTypeType of verifiable credential required
vlab:vcPathJSON path to the claim in the VC

Service Types

Service TypeDescription
TYPE1Basic benchmarking service
TYPE2Intermediate benchmarking service
TYPE3Advanced benchmarking service

Constraint Operators

OperatorDescription
eqEqual to
neqNot equal to

DID Policies

DID policies control what services a user identity can access.

UID Format 

urn:vlab:policy:user:{DID}

Example: urn:vlab:policy:user:did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7

Step 1: Create a DID Policy

Define access rules for a user identity.

Endpoint 

POST /api/v1/policies/dids/{target_did}

Request 

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/policies/dids/did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "0000029f3c8e5a1d7b4e9f2c",
    "password": "WalletPass123!",
    "did": "did:ethr:development:0x1A4c6E9b2D5f7A3c8E1b4D6f9A2c5E7b1D4f6A8c",
    "policy": {
      "@context": [
        "http://www.w3.org/ns/odrl.jsonld",
        { "vlab": "http://vlab.example.org/ns#" }
      ],
      "uid": "urn:vlab:policy:user:did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "type": "Set",
      "assigner": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "profile": "http://vlab.example.org/odrl-profile",
      "permission": [
        {
          "target": "http://vlab.example.org/platform/all",
          "action": [
            {
              "type": "vlab:allowService",
              "refinement": {
                "type": "vlab:serviceType",
                "value": "TYPE1"
              }
            },
            {
              "type": "vlab:allowService",
              "refinement": {
                "type": "vlab:serviceType",
                "value": "TYPE2"
              }
            }
          ],
          "constraint": [
            {
              "leftOperand": "vlab:vcClaim",
              "operator": "eq",
              "rightOperand": "Group1",
              "vlab:vcType": "vlab:CertifiedBenchmarker",
              "vlab:vcPath": "$.credentialSubject.group"
            }
          ]
        }
      ]
    }
  }'

Request Body

FieldTypeRequiredDescription
walletIdstringYesYour wallet ID
passwordstringYesWallet password
didstringYesYour DID (must have LICENSE_MANAGER_ROLE)
policyobjectYesODRL policy object

Policy Validation Rules

  1. UID must match: urn:vlab:policy:user:{target_did}
  2. Action type must be: vlab:allowService
  3. Service type must be: TYPE1, TYPE2, or TYPE3
  4. Constraint operator must be: eq or neq
  5. Constraint value must be: Group1 or Group2

Response (200 OK) 

{}

Error Responses

CodeErrorCause
404WALLET_NOT_FOUNDWallet doesn’t exist
400WRONG_PASSWORDWallet password incorrect
400INVALID_USER_DIDYour DID format invalid
400INVALID_TARGET_DIDTarget DID format invalid
400ALREADY_EXISTSPolicy already exists for this DID
400INVALID_POLICY_FORMATPolicy doesn’t match ODRL schema
400INVALID_POLICY_UIDUID doesn’t match target DID
400INVALID_PERMISSIONSPermission targets are invalid
403INVALID_WALLETWallet doesn’t belong to you
403LICENSE_MANAGER_ROLE_REQUIREDMissing required role
500TRANSACTION_ERRORBlockchain transaction failed

Step 2: Get a DID Policy

Retrieve the policy for a DID you own.

Endpoint 

GET /api/v1/policies/dids/{did}

Request 

curl -X GET "https://middleware-daiedge.bisite.usal.es/api/v1/policies/dids/did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7" \
  -H "x-session-id: {SESSION_ID}"

Response (200 OK) 

{
  "@context": [
    "http://www.w3.org/ns/odrl.jsonld",
    { "vlab": "http://vlab.example.org/ns#" }
  ],
  "uid": "urn:vlab:policy:user:did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "type": "Set",
  "assigner": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "profile": "http://vlab.example.org/odrl-profile",
  "permission": [
    {
      "target": "http://vlab.example.org/platform/all",
      "action": [
        {
          "type": "vlab:allowService",
          "refinement": {
            "type": "vlab:serviceType",
            "value": "TYPE1"
          }
        }
      ],
      "constraint": [
        {
          "leftOperand": "vlab:vcClaim",
          "operator": "eq",
          "rightOperand": "Group1",
          "vlab:vcType": "vlab:CertifiedBenchmarker",
          "vlab:vcPath": "$.credentialSubject.group"
        }
      ]
    }
  ]
}

Error Responses

CodeErrorCause
400INVALID_TARGET_DIDDID format invalid
400POLICY_MISMATCHStored policy doesn’t match blockchain hash
403NOT_OWNER_DIDYou don’t own this DID
404POLICY_NOT_FOUNDNo policy exists for this DID

Step 3: Edit a DID Policy

Update an existing DID policy.

Endpoint 

PUT /api/v1/policies/dids/{target_did}

Request 

curl -X PUT https://middleware-daiedge.bisite.usal.es/api/v1/policies/dids/did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "000003a8d4f7b2c9e6a1d5f8",
    "password": "WalletPass123!",
    "did": "did:ethr:development:0x2C5e7A9b1D4f8B3c6E9a2D5f7A1c4E6b9D2f5A8c",
    "policy": {
      "@context": [
        "http://www.w3.org/ns/odrl.jsonld",
        { "vlab": "http://vlab.example.org/ns#" }
      ],
      "uid": "urn:vlab:policy:user:did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "type": "Set",
      "assigner": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "profile": "http://vlab.example.org/odrl-profile",
      "permission": [
        {
          "target": "http://vlab.example.org/platform/all",
          "action": [
            {
              "type": "vlab:allowService",
              "refinement": {
                "type": "vlab:serviceType",
                "value": "TYPE1"
              }
            },
            {
              "type": "vlab:allowService",
              "refinement": {
                "type": "vlab:serviceType",
                "value": "TYPE2"
              }
            },
            {
              "type": "vlab:allowService",
              "refinement": {
                "type": "vlab:serviceType",
                "value": "TYPE3"
              }
            }
          ]
        }
      ]
    }
  }'

Response (200 OK) 

{}

Error Responses

Same as create, plus:

CodeErrorCause
404POLICY_NOT_FOUNDNo policy exists to edit

Step 4: Remove a DID Policy

Delete a DID policy.

Endpoint 

DELETE /api/v1/policies/dids/{target_did}

Request 

curl -X DELETE https://middleware-daiedge.bisite.usal.es/api/v1/policies/dids/did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "000004b7e5a9c3d8f2b6a1e4",
    "password": "WalletPass123!",
    "did": "did:ethr:development:0x3D6f8A1c4E7b9C2d5F8a1D4e6B9c2F5a8D1e4B7c"
  }'

Request Body

FieldTypeRequiredDescription
walletIdstringYesYour wallet ID
passwordstringYesWallet password
didstringYesYour DID (must have LICENSE_MANAGER_ROLE)

Response (200 OK) 

{}

Error Responses

CodeErrorCause
404WALLET_NOT_FOUNDWallet doesn’t exist
404POLICY_NOT_FOUNDNo policy exists to remove
400WRONG_PASSWORDWallet password incorrect
400INVALID_USER_DIDYour DID format invalid
400INVALID_TARGET_DIDTarget DID format invalid
403INVALID_WALLETWallet doesn’t belong to you
403LICENSE_MANAGER_ROLE_REQUIREDMissing required role
500TRANSACTION_ERRORBlockchain transaction failed

Hardware Policies

Hardware policies control what services a hardware resource can provide.

UID Format 

urn:vlab:policy:device:{hardware_id}

Example: urn:vlab:policy:device:0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6

Note: Hardware ID format is the raw hex string — not a 0x-prefixed bytes32.

Target Format 

urn:vlab:device:{hardware_id}

Example: urn:vlab:device:0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6

Step 5: Create a Hardware Policy

Define what services a hardware resource can provide.

Endpoint 

POST /api/v1/policies/hardware/{hardware_id}

Request 

curl -X POST https://middleware-daiedge.bisite.usal.es/api/v1/policies/hardware/0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6 \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "000005c8f6a2d9e4b7c1f5a8",
    "password": "WalletPass123!",
    "did": "did:ethr:development:0x7018205409a98fb9580b53e268d58c96d58ba640",
    "policy": {
      "@context": [
        "http://www.w3.org/ns/odrl.jsonld",
        { "vlab": "http://vlab.example.org/ns#" }
      ],
      "uid": "urn:vlab:policy:device:0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6",
      "type": "Set",
      "assigner": "did:ethr:development:0x7018205409a98fb9580b53e268d58c96d58ba640",
      "profile": "http://vlab.example.org/odrl-profile",
      "permission": [
        {
          "target": "urn:vlab:device:0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6",
          "action": [
            {
              "type": "vlab:allowService",
              "refinement": {
                "type": "vlab:serviceType",
                "value": "TYPE1"
              }
            },
            {
              "type": "vlab:allowService",
              "refinement": {
                "type": "vlab:serviceType",
                "value": "TYPE2"
              }
            }
          ]
        }
      ],
      "constraint": [
        {
          "leftOperand": "vlab:vcClaim",
          "operator": "eq",
          "rightOperand": "Group1",
          "vlab:vcType": "vlab:CertifiedBenchmarker",
          "vlab:vcPath": "$.credentialSubject.group"
        }
      ]
    }
  }'

Response (200 OK) 

{}

Error Responses

CodeErrorCause
404WALLET_NOT_FOUNDWallet doesn’t exist
404HARDWARE_NOT_FOUNDHardware doesn’t exist
400WRONG_PASSWORDWallet password incorrect
400INVALID_USER_DIDYour DID format invalid
400ALREADY_EXISTSPolicy already exists for this hardware
400INVALID_POLICY_FORMATPolicy doesn’t match ODRL schema
400INVALID_POLICY_UIDUID doesn’t match hardware ID
400INVALID_PERMISSIONSPermission targets don’t match hardware ID
403INVALID_WALLETWallet doesn’t belong to you
403LICENSE_MANAGER_ROLE_REQUIREDMissing required role
500TRANSACTION_ERRORBlockchain transaction failed

Step 6: Get a Hardware Policy

Retrieve the policy for hardware you own.

Endpoint 

GET /api/v1/policies/hardware/{hardware_id}

Request 

curl -X GET "https://middleware-daiedge.bisite.usal.es/api/v1/policies/hardware/0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6" \
  -H "x-session-id: {SESSION_ID}"

Response (200 OK) 

{
  "@context": [
    "http://www.w3.org/ns/odrl.jsonld",
    { "vlab": "http://vlab.example.org/ns#" }
  ],
  "uid": "urn:vlab:policy:device:0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6",
  "type": "Set",
  "assigner": "did:ethr:development:0x7018205409a98fb9580b53e268d58c96d58ba640",
  "profile": "http://vlab.example.org/odrl-profile",
  "permission": [
    {
      "target": "urn:vlab:device:0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6",
      "action": [
        {
          "type": "vlab:allowService",
          "refinement": {
            "type": "vlab:serviceType",
            "value": "TYPE1"
          }
        },
        {
          "type": "vlab:allowService",
          "refinement": {
            "type": "vlab:serviceType",
            "value": "TYPE2"
          }
        }
      ]
    }
  ],
  "constraint": [
    {
      "leftOperand": "vlab:vcClaim",
      "operator": "eq",
      "rightOperand": "Group1",
      "vlab:vcType": "vlab:CertifiedBenchmarker",
      "vlab:vcPath": "$.credentialSubject.group"
    }
  ]
}

Error Responses

CodeErrorCause
400POLICY_MISMATCHStored policy doesn’t match blockchain hash
403NOT_OWNER_DIDYou don’t own this hardware
404HARDWARE_NOT_FOUNDHardware doesn’t exist
404USER_DID_NOT_FOUNDHardware owner DID not found
404POLICY_NOT_FOUNDNo policy exists for this hardware

Step 7: Edit a Hardware Policy

Update an existing hardware policy.

Endpoint 

PUT /api/v1/policies/hardware/{hardware_id}

Request 

curl -X PUT https://middleware-daiedge.bisite.usal.es/api/v1/policies/hardware/0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6 \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "0000019a95f732ce0adb8f69ccc7d362",
    "password": "WalletPass123!",
    "did": "did:ethr:development:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
    "policy": { "...": "updated policy object" }
  }'

Request body structure is the same as Step 5: Create a Hardware Policy.

Error Responses

Same as create, plus:

CodeErrorCause
404POLICY_NOT_FOUNDNo policy exists to edit

Step 8: Remove a Hardware Policy

Delete a hardware policy.

Endpoint 

DELETE /api/v1/policies/hardware/{hardware_id}

Request 

curl -X DELETE https://middleware-daiedge.bisite.usal.es/api/v1/policies/hardware/0000019a9bec41233f591170b9ccee66e618a8ae45e1cbf749190e92f89119f6 \
  -H "Content-Type: application/json" \
  -H "x-session-id: {SESSION_ID}" \
  -d '{
    "walletId": "000006d9f7b3a5e8c2d6f1a4",
    "password": "WalletPass123!",
    "did": "did:ethr:development:0x5F8a1C4d7E9b2A5c8D1f4E7a9C2d5F8b1A4c7E9f"
  }'

Response (200 OK) 

{}

Next Steps

  • Benchmarking - Use policies to control benchmark access
  • Licenses - Request licenses based on policies - WIP

Related Topics

8. Resource Access Control9. Licensing