# Propose intents The `Propose an intent` operation is the entry point for all state changes in Ripple Custody. You need to propose an intent every time you want to change the state of data in Ripple Custody, for example: - Add a new user - Create a blockchain transaction - Release funds from quarantine - Update system properties You can request many types of changes with this operation, however, the procedures below focus on the creation and update of entities. List of intent types For a list of the different types of state changes you can perform with the operation, see the `request.payload.type` drop-down menu in the [API reference](/products/custody/v1.26/api/reference/openapi/intents/createintent#intents/createintent/t=request&path=request/payload&d=0/type). ## Prerequisites To propose an intent, you need the following: - The key pair created during registration. For more information, see [Register](/products/custody/v1.26/api/get-started/register). - A JSON web token. For more information, see [Obtain a JSON web token](/products/custody/v1.26/api/get-started/jwt). ## Propose an intent to create an entity To create an entity: 1. Prepare the intent details in the format shown in [Dry run and signature request body](/products/custody/v1.26/api/reference/intent-structure#dry-run-and-signature-request-body). The following example creates a new account: ```json { "author": { "id": "461dac3d-55c6-4ce8-9ce2-dfb97cfbe279", "domainId": "67241e7d-f345-459e-9293-475693c45d85" }, "expiryAt": "2021-08-09T23:47:16.448Z", "targetDomainId": "67241e7d-f345-459e-9293-475693c45d85", "id": "3949c4aa-f929-11eb-bba2-dcfb48cfb3cb", "payload": { "id": "3b6d578e-7396-495d-8392-61b7ede174b3", "alias": "btc-zero", "providerDetails": { "vaultId": "00000000-0000-0000-0000-000000000000", "keyStrategy": "VaultHard", "type": "Vault" }, "ledgerIds": ["bitcoin-testnet"], "lock": "Unlocked", "description": "a bitcoin account for testing", "customProperties": { "testnet_account": "true" }, "type": "v0_CreateAccount" }, "description": "Intent to create an account", "customProperties": {}, "type": "Propose" } ``` To get details of your author ID and associated domain ID, see [Check your user information](/products/custody/v1.26/api/get-started/register#check-your-user-information). 2. Send the request body to a signing service, as described in [Sign intents](/products/custody/v1.26/api/get-started/key-operations/update/intent-signature). 3. Create the full intent request body in the format shown in [Propose an intent request body](/products/custody/v1.26/api/reference/intent-structure#propose-an-intent-request-body), including the signature from the previous step: ```json { "request": { "author": { "id": "461dac3d-55c6-4ce8-9ce2-dfb97cfbe279", "domainId": "67241e7d-f345-459e-9293-475693c45d85" }, "expiryAt": "2021-08-09T23:47:16.448Z", "targetDomainId": "67241e7d-f345-459e-9293-475693c45d85", "id": "3949c4aa-f929-11eb-bba2-dcfb48cfb3cb", "payload": { "id": "3b6d578e-7396-495d-8392-61b7ede174b3", "alias": "btc-zero", "providerDetails": { "vaultId": "00000000-0000-0000-0000-000000000000", "keyStrategy": "VaultHard", "type": "Vault" }, "ledgerIds": ["bitcoin-testnet"], "lock": "Unlocked", "description": "a bitcoin account for testing", "customProperties": { "testnet_account": "true" }, "type": "v0_CreateAccount" }, "description": "Intent to create an account", "customProperties": {}, "type": "Propose" }, "signature": "" } ``` 4. Call the [Propose an intent](/products/custody/v1.26/api/reference/openapi/intents/createintent) operation, with the signed request body and the following headers: ```sh -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'requestId: ' ``` The inclusion of a request ID is optional but highly recommended, for traceability purposes. If you do not include it, Ripple Custody generates the request ID for you and returns it in the response. Ripple Custody returns a response that includes the request ID: ```json { "requestId": "8737c2a2-e8e1-46bf-a2a4-9918437f4a29" } ``` You can use the request ID to trace the request, as described in [Check the request](/products/custody/v1.26/api/get-started/key-operations/update/check#check-the-request). ## Propose an intent to update an entity Most of the entities in Ripple Custody can be updated, although there are some exceptions, such as transaction orders. Intents to update entities follow the standard intent creation process. To create an update intent, follow the process described in [Propose an intent to create an entity](#propose-an-intent-to-create-an-entity), replacing the `payload` block of the request body with a block similar to the following example: ```json { "payload": { "reference": { "id": "42bbd0e1-ce76-11eb-a921-dcfb48cfb3cb", "revision": 1 }, "alias": "A new alias for the user", "roles": [ "manager", "newRole" ], "description": "The user has been updated", "customProperties": {}, "type": "v0_UpdateUser" } } ``` ## Propose an intent to lock or unlock an entity Any entity in Ripple Custody can be locked (inactive) or unlocked (active). It is not possible to perform an action on an inactive entity, however, it is possible to query and read the properties of an inactive entity. When you create an entity with an intent, you specify a value for the `lock` property. You can update the property with a `Lock` or `Unlock` intent corresponding to the entity. Intents to lock or unlock entities follow the standard intent creation process. To create a lock or unlock intent, follow the process described in [Propose an intent to create an entity](#propose-an-intent-to-create-an-entity), replacing the `payload` block of the request body with a block similar to the following examples: Lock domain example: ```json { "payload": { "reference": { "id": "88e4f7a4-befc-11eb-8588-dcfb48cfb3cb", "revision": 1 }, "type": "v0_LockDomain" } } ``` Unlock domain example: ```json { "payload": { "reference": { "id": "88e4f7a4-befc-11eb-8588-dcfb48cfb3cb", "revision": 1 }, "type": "v0_UnlockDomain" } } ``` In both cases, the payload contains a `reference` object, which contains the `id` of the entity to lock or unlock, and the `revision` number. For most entities, the target domain of the entity to lock or unlock is the domain where the entity resides. For domains, the target domain is the parent domain of the domain to unlock. Root domains have no parent, so once locked, they can't be unlocked.