Create your sandbox account and identity

Start with an API key and secret from your broker/Neuron operator. By the end, you will have an enabled sandbox account, an authenticated session, a signing key, and an approved test Legal Identity. The examples show HTTP requests you can send from any backend language or API client. If you already have an account, use Sign in with an existing account.

Before you start

You need:

An account-creation API key and its secret supplied by the operator for this sandbox.
A new username, an email address you control, and an account password.
A separate password for the signing key you will create.
A reachable HTTPS URL identifying your application, sent as Referer on every request. A public project page can serve this purpose.

Use the sandbox over HTTPS:

https://sandbox.neuro-tech.io

In signed messages, the host is exactly sandbox.neuro-tech.io, without the scheme or a path. This is a shared development environment; other Neurons have their own hosts and credentials.

The sandbox has public account enablement and automatic identity approval. An approved sandbox identity does not mean its claims were verified.

Understand the sequence

The API secret authorizes account creation. The account password authorizes login and later signed requests. The signing-key password authorizes use of that key. Keep all three secrets in your backend.

1. Create an account with your API key

Generate a fresh nonce from 32 random bytes, encoded as Base64. Define HMAC(secret, message) as HMAC-SHA-256 over the UTF-8 message, using the UTF-8 secret as the key, with a standard Base64 result. For this example without a phone number, calculate:

message = userName:host:eMail:password:apiKey:nonce
signature = HMAC(apiSecret, message)

Join the actual values with : in that exact order, without added spaces or line breaks. Sign these values, not the JSON body. If you supply a phone number, use the phone-inclusive signature. Send the following request, replacing every placeholder:

POST /Agent/Account/Create HTTP/1.1
Host: sandbox.neuro-tech.io
Referer: https://your-app.example/
Accept: application/json
Content-Type: application/json

{
  "userName": "<NEW_USERNAME>",
  "eMail": "<YOUR_EMAIL>",
  "password": "<ACCOUNT_PASSWORD>",
  "apiKey": "<API_KEY>",
  "nonce": "<FRESH_NONCE>",
  "signature": "<SIGNATURE>",
  "seconds": 3600,
  "language": "en"
}

No bearer token is needed. The API secret is used locally for signing and is not included in the request. The response includes created, enabled, jwt, and expires. A new account can be disabled; continue with sandbox enablement before relying on the returned session. Keep the username and password you chose. See Create account for the full response.

2. Enable the sandbox account

The sandbox provides this public helper so you can enable the account before logging in:

POST /hackathon-contract-approver/account/enable HTTP/1.1
Host: sandbox.neuro-tech.io
Referer: https://your-app.example/
Accept: application/json
Content-Type: application/json

{"account":"<NEW_USERNAME>"}

Use the account’s username, not its Legal Identity ID or full JID. No API key, password, or JWT is required for this sandbox helper. Expected response shape:

{
  "account": "<NEW_USERNAME>",
  "enabled": true,
  "already_enabled": false
}

Repeating this enablement request is supported; already_enabled becomes true. An unknown account returns 404. This helper enables the account; it does not verify ownership of its email address or phone number. Generate a new nonce and calculate:

message = userName:host:nonce
signature = HMAC(accountPassword, message)

POST /Agent/Account/Login HTTP/1.1
Host: sandbox.neuro-tech.io
Referer: https://your-app.example/
Accept: application/json
Content-Type: application/json

{
  "userName": "<NEW_USERNAME>",
  "nonce": "<NEW_NONCE>",
  "signature": "<LOGIN_SIGNATURE>",
  "seconds": 3600
}

Keep the returned jwt in memory. Send it as Authorization: Bearer <JWT> on the remaining /Agent/ requests. Confirm the account with:

POST /Agent/Account/Info HTTP/1.1
Host: sandbox.neuro-tech.io
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{}

Confirm the response refers to your account and reports it as enabled. Login does not itself create a Legal Identity.

4. Select an algorithm and create a signing key

Call POST /Agent/Crypto/GetAlgorithms with {} and the same authenticated headers. Choose a signing algorithm from Algorithms that is marked safe, and retain its exact localName and namespace. Choose a new key identifier, such as sandbox-identity-key, and a separate key password. The key identifier belongs to your account; it is unrelated to your account-creation API key. Using a fresh nonce, calculate:

keyMessage = userName:host:localName:namespace:keyId
keySignature = HMAC(keyPassword, keyMessage)
requestSignature = HMAC(accountPassword, keyMessage:keySignature:nonce)

POST /Agent/Crypto/CreateKey HTTP/1.1
Host: sandbox.neuro-tech.io
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "localName": "<SELECTED_LOCAL_NAME>",
  "namespace": "<SELECTED_NAMESPACE>",
  "id": "sandbox-identity-key",
  "nonce": "<NEW_NONCE>",
  "keySignature": "<KEY_SIGNATURE>",
  "requestSignature": "<REQUEST_SIGNATURE>"
}

Success returns created and updated. Retain the id you submitted as your keyId, together with the algorithm’s localName and namespace. Use a fresh key ID for a new key; do not overwrite an existing key unintentionally.

5. Apply for a test Legal Identity

For this sandbox example, use fictional first and last names: FN is Alex and LN is Sandbox. The sandbox review does not verify the truth of identity claims or photos. Retrieve application requirements with {} and the authenticated headers before choosing properties and evidence. Other providers can require additional fields and documents. Keep the same key message from step 4, generate a fresh nonce, and append each property’s name and value in the same order as the Properties array:

keySignature = HMAC(keyPassword, keyMessage)
message = keyMessage:keySignature:nonce:FN:Alex:LN:Sandbox
requestSignature = HMAC(accountPassword, message)

POST /Agent/Legal/ApplyId HTTP/1.1
Host: sandbox.neuro-tech.io
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "keyId": "sandbox-identity-key",
  "nonce": "<NEW_NONCE>",
  "keySignature": "<KEY_SIGNATURE>",
  "requestSignature": "<IDENTITY_REQUEST_SIGNATURE>",
  "Properties": [
    {"name":"FN","value":"Alex"},
    {"name":"LN","value":"Sandbox"}
  ]
}

Replace https://your-app.example/ with your reachable application URL: identity application validates Referer. The response contains Identity; retain its id as your legalId. The identity’s status is nested under Identity.status, not a top-level account state.

6. Upload the required attachments

In the sandbox, the identity may be approved automatically as soon as it is created, before attachments or ReadyForApproval. Check Identity.status.state using GetIdentity. If it is already Approved, skip steps 6 and 7 and continue with the approved identity. Attachments cannot be added after approval; contact the sandbox operator if you need to test an application with evidence uploads. Before submitting for review, add the photos or documents required by the selected review method. Use test evidence for this sandbox exercise. If no attachments are required, continue to step 7. Follow Prepare, sign, and upload an identity attachment for the complete AddIdAttachment request. It sends Base64 file bytes, the filename, and the content type in signed JSON. Use the legalId from step 5 and the same signing key. Upload each file while the identity is Created and wait for all uploads to succeed.

7. Submit the application for automatic review

Check the current identity state before sending this request. If the sandbox has already set it to Approved, ReadyForApproval is not needed. Continue to step 8. If the identity is still Created, call ReadyForApproval after the required uploads, even when no attachments are needed. This starts the normal review process. Use the same key message as step 4, and generate a fresh nonce:

keySignature = HMAC(keyPassword, keyMessage)
message = keyMessage:keySignature:nonce:legalId
requestSignature = HMAC(accountPassword, message)

POST /Agent/Legal/ReadyForApproval HTTP/1.1
Host: sandbox.neuro-tech.io
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "keyId": "sandbox-identity-key",
  "legalId": "<IDENTITY_ID_FROM_APPLY_ID>",
  "nonce": "<NEW_NONCE>",
  "keySignature": "<KEY_SIGNATURE>",
  "requestSignature": "<READY_REQUEST_SIGNATURE>"
}

The response contains Identity. Check its identifier and current state, then observe the review result.

8. Confirm automatic approval

Retrieve your identity to check whether the sandbox approved it automatically or to observe the result after ReadyForApproval:

POST /Agent/Legal/GetIdentity HTTP/1.1
Host: sandbox.neuro-tech.io
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{"legalId":"<IDENTITY_ID_FROM_APPLY_ID>"}

Wait for Identity.status.state to become Approved. A response can initially show Created while approval is pending. Poll with a bounded interval, such as every two seconds for up to 30 seconds; that is a client timeout choice, not an approval-time guarantee. If approval remains pending, check that ReadyForApproval succeeded and contact the sandbox operator with your legalId. Do not create another identity or use a direct approval helper to skip submission and review. If ReadyForApproval reports that the identity is no longer Created, retrieve it again. Sandbox approval may have completed between your state check and the request; an Approved identity needs no further readiness call.

Keep the result and continue building

Value	Purpose
Sandbox host and username	Identify the account used by your application.
Account password	Authorize login and signed requests; keep it in your secret store.
`jwt` and `expires`	Authenticate requests for the current session.
`keyId`, `localName`, `namespace`	Identify the signing key and its algorithm.
Key password	Authorize use of the signing key; store it separately from public metadata.
`legalId` and observed `Approved` state	Identify the sandbox identity used in later signing workflows.

Continue with contract authoring or a token with a state machine and Script. Those workflows can require additional parties and provider signatures. The request signing and sequence are checked with local tests. The sandbox host and public helper reference have been checked; this complete account-to-identity run still requires testing with operator-issued credentials.

Troubleshoot a blocked step

Symptom	Check
API key not found or account limit reached	Use a key issued for this sandbox and ask its operator about the quota.
Username already exists	Use a new username, or sign in to the existing account.
Login fails after creation	Enable the exact username through the sandbox helper before logging in.
Signature invalid	Check the secret used, exact host, field order, UTF-8 encoding, and Base64 output.
Identity application rejects `Referer`	Supply a reachable application URL, including on backend requests.
Identity remains `Created`	Confirm uploads completed and `ReadyForApproval` succeeded, then poll or contact the operator; do not apply again.
Request times out after a write	Check the account or identity already created before resending the write.

Move beyond the sandbox

Use the host and credentials supplied for your production Neuron. Replace sandbox enablement with the required contact-verification process, and automatic identity approval with the provider’s evidence and review procedure. See account creation and identity approval.

Start here

Make requests

Reliability and security

API reference

Endpoints

Before you start

Understand the sequence

1. Create an account with your API key

2. Enable the sandbox account

4. Select an algorithm and create a signing key

5. Apply for a test Legal Identity

6. Upload the required attachments

7. Submit the application for automatic review

8. Confirm automatic approval

Keep the result and continue building

Troubleshoot a blocked step

Move beyond the sandbox

​Before you start

​Understand the sequence

​1. Create an account with your API key

​2. Enable the sandbox account

​3. Sign in and check the account

​4. Select an algorithm and create a signing key

​5. Apply for a test Legal Identity

​6. Upload the required attachments

​7. Submit the application for automatic review

​8. Confirm automatic approval

​Keep the result and continue building

​Troubleshoot a blocked step

​Move beyond the sandbox

Before you start

Understand the sequence

1. Create an account with your API key

2. Enable the sandbox account

3. Sign in and check the account

4. Select an algorithm and create a signing key

5. Apply for a test Legal Identity

6. Upload the required attachments

7. Submit the application for automatic review

8. Confirm automatic approval

Keep the result and continue building

Troubleshoot a blocked step

Move beyond the sandbox