Organization Management
Organization endpoints allow you to configure settings for your organization including webhooks, API key rotation, and multi-signature withdrawal requirements.
The organization model
The organization model contains configuration and settings for your entire organization.
Properties
- Name
id- Type
- string
- Description
Unique identifier for the organization.
- Name
name- Type
- string
- Description
Organization name.
- Name
webhookUrl- Type
- string
- Description
HTTPS URL where webhook notifications will be sent.
- Name
webhookSigningSecret- Type
- string
- Description
Secret used to sign webhook payloads (HMAC-SHA256).
- Name
minWithdrawalSigners- Type
- number
- Description
Minimum number of approvals required for withdrawals (1 for auto-approval).
- Name
createdAt- Type
- timestamp
- Description
Timestamp of when the organization was created.
- Name
updatedAt- Type
- timestamp
- Description
Timestamp of when the organization was last updated.
Get organization details
Retrieve your organization's current settings and configuration.
Request
curl https://api.coinspayd.io/organisation \
-H "x-api-key: {your-api-key}"
Response
{
"id": "org_456",
"name": "Acme Corporation",
"webhookUrl": "https://api.acme.com/webhooks/coinspayd",
"webhookSigningSecret": "550e8400-e29b-41d4-a716-446655440000",
"minWithdrawalSigners": 2,
"createdAt": "2025-01-01T00:00:00.000Z",
"updatedAt": "2025-01-15T10:00:00.000Z"
}
Rotate API key
Generate a new API key for the authenticated user. The old key will be immediately invalidated.
Request
curl -X PATCH https://api.coinspayd.io/organisation/api-key \
-H "Authorization: Bearer {jwt-token}"
Response
{
"apiKey": "new-550e8400-e29b-41d4-a716-446655440000"
}
Update webhook URL
Update the HTTPS URL where webhook notifications will be sent for deposits and withdrawals.
Required attributes
- Name
webhookUrl- Type
- string
- Description
HTTPS URL for receiving webhooks (must use HTTPS).
Request
curl -X PATCH https://api.coinspayd.io/organisation/webhook \
-H "x-api-key: {your-api-key}" \
-H "Content-Type: application/json" \
-d '{
"webhookUrl": "https://api.acme.com/webhooks/coinspayd"
}'
Response
{}
Rotate webhook signing secret
Generate a new webhook signing secret. Use this to verify webhook authenticity via HMAC-SHA256 signatures.
Request
curl -X PATCH https://api.coinspayd.io/organisation/webhook/signing-secret \
-H "x-api-key: {your-api-key}"
Response
{
"webhookSigningSecret": "new-uuid-secret"
}
Update minimum withdrawal signers
Configure the number of approvals required before a withdrawal is processed.
Required attributes
- Name
minWithdrawalSigners- Type
- number
- Description
Minimum number of signers (must be >= 1). Set to 1 for auto-approval.
Request
curl -X PATCH https://api.coinspayd.io/organisation/min-withdrawal-signers \
-H "x-api-key: {your-api-key}" \
-H "Content-Type: application/json" \
-d '{
"minWithdrawalSigners": 3
}'
Response
{}
Multi-signature withdrawal flow
Understanding how minWithdrawalSigners affects withdrawals:
Single Signer (minWithdrawalSigners = 1)
- Withdrawals are automatically approved upon creation
- Status flow:
Pending→Processing→Completed - Recommended for: Small amounts, trusted environments
Multi-Signature (minWithdrawalSigners > 1)
- Withdrawals require multiple approvals before processing
- Status flow:
PendingApproval→Pending→Processing→Completed - Recommended for: Large amounts, enterprise security
Example with 3 signers required:
- User A creates withdrawal (
PendingApproval, 1 signer) - User B approves withdrawal (
PendingApproval, 2 signers) - User C approves withdrawal (
Pending, 3 signers - threshold met) - System processes withdrawal (
Processing→Completed)
Webhook signature verification
Verify webhook authenticity using the signing secret:
const crypto = require('crypto')
function verifyWebhook(payload, signature, secret) {
const hmac = crypto.createHmac('sha256', secret)
const digest = hmac.update(JSON.stringify(payload)).digest('hex')
return signature === digest
}
// Express.js example
app.post('/webhooks/coinspayd', (req, res) => {
const signature = req.headers['x-signature']
const isValid = verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)
if (!isValid) {
return res.status(401).send('Invalid signature')
}
// Process webhook...
res.status(200).send('OK')
})
import hmac
import hashlib
import json
def verify_webhook(payload, signature, secret):
digest = hmac.new(
secret.encode(),
json.dumps(payload).encode(),
hashlib.sha256
).hexdigest()
return signature == digest
# Flask example
@app.route('/webhooks/coinspayd', methods=['POST'])
def webhook():
signature = request.headers.get('X-Signature')
is_valid = verify_webhook(request.json, signature, os.environ['WEBHOOK_SECRET'])
if not is_valid:
return 'Invalid signature', 401
# Process webhook...
return 'OK', 200