Create Policy Rules
Overview
Create policy rules to define what must to occur (actions) before users can execute sensitive operations (touchpoints) on things within your enterprise (scopes) during specific scenarios (conditions).
Important Terms
Term | Description | Example |
---|---|---|
Scope | An entity, or set of entities, that you can control using a policy rule. | Hot wallets |
Touchpoint | An event that can occur on a scope and can trigger a policy rule. | Withdrawals |
Condition | Defines the exact criteria surrounding the touchpoint that's required to trigger the policy. | Withdraw initiated by a specific user |
Action | Something that must occur for the touchpoint to complete or something that automatically occurs, completing the touchpoint. | Require approval from specific users or automatic approval |
Prerequisites
- Get Started
- Wallets Overview (set up your wallets)
- Add Wallet Users (optional)
1. Get Scope ID
Before you can create a policy rule, you must get the scope ID for the scope you want to create the rule for.
Endpoint: List Scopes
1 2 3 4 5 6 7
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>" export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>" curl -X GET \ "https://app.bitgo-test.com/api/policy/v1/enterprises/$ENTERPRISE_ID/scopes" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN"
Step Result
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74
{ "scopes": [ { "id": "c8234a0f-7722-44d7-bedc-bfded7bd24a7", "name": "wallet.segregated", "label": "Wallet", "description": "A BitGo Wallet", "conditions": [ { "name": "wallet.type", "label": "Wallet Type", "description": "Allows creating a Condition based on the Wallet Type", "status": "ACTIVE", "parameters": [ { "name": "walletType", "label": "Type", "description": "The Wallet Type", "type": "ENUMERATED", "required": "ALWAYS", "allowMultiple": true, "values": [ { "value": "custodial", "label": "Custody Wallet", "description": "A custody wallet" }, { "value": "hot", "label": "Hot Wallet", "description": "A hot wallet" }, { "value": "cold", "label": "Self-custody cold wallet", "description": "A cold wallet" }, { "value": "trading", "label": "Go Account", "description": "A trading wallet" } ] } ] }, { "name": "wallet.ids", "label": "Single Wallet", "description": "Allows creating a Condition based on the Wallet Id", "status": "ACTIVE", "parameters": [ { "name": "walletId", "label": "Wallet Id", "description": "The Wallet Ids", "type": "BITGO_WALLET_ID", "required": "ALWAYS", "allowMultiple": false, "values": [] } ] }, { "name": "wallet.all", "label": "All wallets in my enterprise", "description": "Applies to All Wallets", "status": "ACTIVE", "parameters": [] } ] } ] }
2. Get Touchpoint Name
Using the scope ID returned in the prior step, you can now list all the available touchpoints for the given scope.
Endpoint: List Touchpoints
1 2 3 4 5 6 7 8
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>" export SCOPE_ID="<SCOPE_ID>" export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>" curl -X GET \ "https://app.bitgo-test.com/api/policy/v1/enterprises/$ENTERPRISE_ID/scopes/$SCOPE_ID/touchpoints" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN"
Step Result
You return all possible touchpoints for the given scope. Save the touchpoint name that you want to create a policy rule for, because you must pass it in the following step.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
{ "touchpoints": [ { "id": "166082ab-9268-4369-996a-b4ac63f6f634", "name": "wallet.segregated.transfer", "status": "ACTIVE", "label": "Withdrawal", "description": "Withdrawal from a BitGo Wallet", "adminOnly": false }, { "id": "0e0c1126-daf3-4b79-a05c-094ebd30007d", "name": "goaccount.settlement.signed", "status": "ACTIVE", "label": "Settlement Initiated", "description": "When a settlement is initiated from a BitGo Go Account Wallet", "adminOnly": false }, { "id": "8c0a1a3f-7f20-4ff1-aa8a-ac28a217f3f3", "name": "goaccount.settlement.countersigned", "status": "ACTIVE", "label": "Settlement Approved", "description": "When a settlement is accepted by a user on a BitGo Go Account Wallet", "adminOnly": false } ], "page": 1, "totalPages": 1, "totalElements": 3 }
3. Create Policy Rule
Using the touchpoint name returned in the prior step, you can now create a policy rule for the given touchpoint. The following example creates a policy rule that requires approval from a specific user for withdrawals of more than 2 TBTC from a specific wallet.
Endpoint: Create Policy Rule
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
export ENTERPRISE_ID="<YOUR_ENTERPRISE_ID>" export TOUCHPOINT="<TOUCHPOINT_NAME>" export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>" export USER_ID="<APPROVER_USER_ID>" export WALLET_ID="<WALLET_ID>" curl -X POST \ "https://app.bitgo-test.com/api/policy/v1/enterprises/$ENTERPRISE_ID/touchpoints/$TOUCHPOINT/rules" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -d '{ "name": "Spending limit - require approval on withdrawals of more than 2 TBTC", "adminOnly": false, "clauses": [ { "conditions": [ { "name": "transfer.amount", "parameters": { "operator": ">", "amount": "200000000", "coin": "tbtc" } } ], "actions": [ { "name": "approvals.customer.enterpriseUser", "parameters": { "userIds": [ "'"$USER_ID"'" ], "minRequired": "1", "initiatorIsAllowedToApprove": false } } ] } ], "filteringConditions": [ { "name": "wallet.ids", "parameters": { "walletId": [ "'"$WALLET_ID"'" ] } } ] }'
Step Result
The new policy rule enters a PENDING_APPROVAL
status. If the new policy rule doesn't require approval, it automatically updates to ACTIVE
status within a short period of time. If you it requires approval, the policy rule remains in the PENDING_APPROVAL
status until a wallet admin approves it.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
{ "uniqueId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05", "id": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad", "name": "Spending limit - require approval on withdrawals of more than 2 TBTC", "status": "PENDING_APPROVAL", "adminOnly": false, "touchpointId": "166082ab-9268-4369-996a-b4ac63f6f634", "scopeId": "c8234a0f-7722-44d7-bedc-bfded7bd24a7", "touchpointLabel": "Withdrawal", "scopeLabel": "Wallet", "clauses": [ { "actions": [ { "name": "approvals.customer.enterpriseUser", "parameters": { "userIds": ["62ab90e06dfda30007974f0a52a12995"], "minRequired": "1", "initiatorIsAllowedToApprove": false } } ], "conditions": [ { "name": "transfer.amount", "parameters": { "operator": ">", "amount": "200000000", "coin": "tbtc" } } ] } ], "filteringConditions": [ { "name": "wallet.ids", "parameters": { "walletId": ["654ec786c07fe8dc0dcfe03916ec5bb0"] } } ], "locked": false, "lockType": "LOCK_AFTER_DATE", "lockDate": "2024-04-14T18:52:07.955224Z", "createdDate": "2024-04-12T18:52:07.955235Z", "modifiedDate": "2024-04-12T18:52:08.041738Z", "enterpriseId": "62c5ae8174ac860007aff138a2d74df7", "createdBy": "62ab90e06dfda30007974f0a52a12995", "modifiedBy": "62ab90e06dfda30007974f0a52a12995", "evaluationId": "57cd4e69-8038-4568-8124-55ca80ff94c1" }
4. Approve Policy Rule (Optional)
Note: If you configure an approval requirement for policy rules, you can't approve your own policy-rule changes - another admin must approve them.
4.1 Get Pending-Approval ID
To update a pending approval, you must get the pending-approval ID for the pending approval you want to respond to.
Endpoint: List Pending Approvals
1 2 3 4 5 6
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>" curl -X GET \ https://app.bitgo-test.com/api/v2/pendingApprovals \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $ACCESS_TOKEN"
Step Result
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
{ "pendingApprovals": [ { "id": "661982d8e1ee8192595fed2145490e13", "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0", "enterprise": "62c5ae8174ac860007aff138a2d74df7", "bitgoOrg": "BitGo Trust", "creator": "62ab90e06dfda30007974f0a52a12995", "createDate": "2024-04-12T18:52:08.072Z", "info": { "type": "genericRequest", "genericRequest": { "description": "Request to create policy rule {policyRuleId}", "anchors": [ { "key": "policyRuleId", "value": "835c75f8-49e2-4d5b-82f0-0c8829d52a05", "anchorType": "policyRuleId" } ], "proposedId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05", "resourceType": "policyRule", "changeType": "create", "metadata": { "sharedId": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad", "policyRuleName": "Spending limit - require approval on withdrawals of more than 2 TBTC" } } }, "approvers": [ "621d08a634ad8a0007fcddffd7c429cc", "627ff9325a5c1b0007c05a40d15e1522" ], "state": "pending", "scope": "wallet", "userIds": [ "62ab90e06dfda30007974f0a52a12995", "621d08a634ad8a0007fcddffd7c429cc", "627ff9325a5c1b0007c05a40d15e1522" ], "approvalsRequired": 1, "singleRunResults": [], "resolvers": [], "policyEvaluationId": "57cd4e69-8038-4568-8124-55ca80ff94c1", "actions": [ { "id": "65a52063-df3b-4362-bfc1-68d4e8b2cc6f", "status": "PENDING", "name": "approvals.customer.walletAdmin", "parameters": { "userIds": [] }, "resolvers": [], "approvers": [ "621d08a634ad8a0007fcddffd7c429cc", "627ff9325a5c1b0007c05a40d15e1522" ] } ], "resolutionOrder": [ { "actions": ["65a52063-df3b-4362-bfc1-68d4e8b2cc6f"] } ] } ] }
4.2 Approve Pending Approval
Endpoint: Update Pending Approval
1 2 3 4 5 6 7 8 9 10 11 12
export APPROVAL_ID="<APPROVAL_ID>" export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>" export OTP="<YOUR_OTP>" curl -X PUT \ https://app.bitgo-test.com/api/v2/pendingApprovals/$APPROVAL_ID \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -d '{ "state": "approved", "otp": "'"$OTP"'" }'
Step Result
You approved the policy.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
{ "id": "661982d8e1ee8192595fed2145490e13", "wallet": "654ec786c07fe8dc0dcfe03916ec5bb0", "enterprise": "62c5ae8174ac860007aff138a2d74df7", "bitgoOrg": "BitGo Trust", "creator": "62ab90e06dfda30007974f0a52a12995", "createDate": "2024-04-12T18:52:08.072Z", "approvedDate": "2024-04-12T18:58:29.774Z", "info": { "type": "genericRequest", "genericRequest": { "description": "Request to create policy rule {policyRuleId}", "anchors": [ { "key": "policyRuleId", "value": "835c75f8-49e2-4d5b-82f0-0c8829d52a05", "anchorType": "policyRuleId" } ], "proposedId": "835c75f8-49e2-4d5b-82f0-0c8829d52a05", "resourceType": "policyRule", "changeType": "create", "metadata": { "sharedId": "5e43e1b6-665d-4406-b59a-b9e1d2e9dfad", "policyRuleName": "Spending limit - require approval on withdrawals of more than 2 TBTC" } } }, "approvers": [], "state": "approved", "scope": "wallet", "userIds": [ "62ab90e06dfda30007974f0a52a12995", "621d08a634ad8a0007fcddffd7c429cc", "627ff9325a5c1b0007c05a40d15e1522" ], "approvalsRequired": 1, "singleRunResults": [], "resolvers": [ { "user": "627ff9325a5c1b0007c05a40d15e1522", "date": "2024-04-12T18:58:29.655Z", "resolutionType": "pending", "resolutionAction": "approve" } ], "policyEvaluationId": "57cd4e69-8038-4568-8124-55ca80ff94c1", "actions": [ { "id": "65a52063-df3b-4362-bfc1-68d4e8b2cc6f", "status": "COMPLETE", "name": "approvals.customer.walletAdmin", "parameters": { "userIds": [] }, "resolvers": [ { "user": "627ff9325a5c1b0007c05a40d15e1522", "date": "2024-04-12T18:58:29.655Z", "resolutionType": "pending", "resolutionAction": "approve" } ], "approvers": ["621d08a634ad8a0007fcddffd7c429cc"] } ], "resolutionOrder": [{ "actions": ["65a52063-df3b-4362-bfc1-68d4e8b2cc6f"] }] }
Next Steps
You can review your new policy rule by calling the List policy rules endpoint.