Client Security

901 προβολές Markdown

The five endpoints that manage the password, verification, two-step sign-in and the security rules set on a client.

Overview

These five endpoints carry the security decisions an operator applies to a client account: setting the password, marking a field verified, turning on two-step verification, tightening sign-in and payment rules, and limiting support access.

None of them ask the client anything. They all apply directly, which is why a key carrying these endpoints is worth keeping narrow.

Reference

Changing the Password

put/api/v1/admin/clients/{id}/password
Clients/SetClientPassword admin no old password asked

Sets the client's password directly. The current one is not asked for.

Body 2
passwordstringrequiredThe new password. At least options/password-length characters; defaults to 6.
password_confirmationstringIf sent, it must match password exactly. Leave it out and no check is made.
Response fields data — 1
changedboolWhether the password was changed.
Errors 5
not_found404No such client.
password_required422The password is empty.
password_too_short422The password is below the minimum length. The limit comes back in error.details.min.
password_mismatch422The confirmation does not match the password.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/password' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"password":"Str0ngP@ssw0rd","password_confirmation":"Str0ngP@ssw0rd"}'
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/password', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    password: 'Str0ngP@ssw0rd',
    password_confirmation: 'Str0ngP@ssw0rd',
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/password');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'password'              => $newPassword,
        'password_confirmation' => $newPassword,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$response = Api::Clients()->SetClientPassword([
    'id'       => 42,
    'password' => $newPassword,
]);

Verifying Email and Phone

post/api/v1/admin/clients/{id}/verify
Clients/VerifyClient admin

Marks a field as verified. No code is sent to the client; the flag is set directly.

Body 1
typestringrequiredemail or phone.
Response fields data — 2
verifiedboolWhether the verification was applied.
typestringThe field that was verified: email or phone.
Errors 3
not_found404No such client.
type_invalid422type is neither of the two values.
insufficient_scope403The key lacks the required scope.
Request 
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/verify' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"type":"email"}'
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/verify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ type: 'email' }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/verify');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['type' => 'email']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// You set the flag here after running your own verification flow.
$response = Api::Clients()->VerifyClient([
    'id'   => 42,
    'type' => 'email',
]);

Two-Step Verification

put/api/v1/admin/clients/{id}/2fa
Clients/SetClient2fa admin

Turns the client's two-step verification on or off; a method that could not deliver its code is refused and nothing is written. Turning it off also closes the client's open sessions and removes their trusted devices.

Body 2
enabledboolrequiredTurns it on or off.
methodstringThe method to switch on: Email or Sms. It must be active in the 2FA method list and its delivery channel needs a module (mail/SMTP for Email, SMS for Sms); Sms also needs a mobile phone number on the client. Totp needs the client's own authenticator setup and is refused. Required only when enabling; not needed to disable.
Response fields data — 2
enabledboolThe two-step state as it now stands.
methodstringThe module that was selected. Comes back only when enabling.
Errors 7
not_found404No such client.
method_required422method was missing on an enable request.
method_unknown422The method is unknown, not active in the 2FA method list, or its module is missing. details carries method.
method_requires_setup422The method needs the client's own setup (Totp); the client enables it from their account. details carries method.
delivery_channel_unavailable422The method's delivery channel has no module: Email needs a mail module, Sms an SMS module. details carries method and channel (mail or sms).
recipient_missing422Sms was chosen but the client has no mobile phone number. details carries method.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/2fa' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"enabled":true,"method":"Email"}'
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/2fa', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ enabled: true, method: 'Email' }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/2fa');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'enabled' => true,
        'method'  => 'Email',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// You do not need to send a method when turning it off.
$response = Api::Clients()->SetClient2fa([
    'id'      => 42,
    'enabled' => false,
]);

Security Settings

patch/api/v1/admin/clients/{id}/security-settings
Clients/UpdateClientSecuritySettings admin

Changes the security rules that apply to this client. Only the fields you send change.

Body 6
block_proxyboolBlocks sign-in from behind a proxy.
allow_proxyboolExempts this client from the proxy check.
require_birthdayboolMakes the date of birth required.
require_adult_ageboolRequires an over-18 check.
force_document_filtersint[]Ids of the document verification filters to enforce. List: clients/document-filters.
blocked_gatewaysstring[]Keys of the payment methods closed to this client.
Response fields data — 6
block_proxyboolWhether sign-in from behind a proxy is blocked. The whole state comes back, not only the part you sent.
allow_proxyboolWhether the client is exempt from the proxy check.
require_birthdayboolWhether the date of birth is required.
require_adult_ageboolWhether the over-18 check is on.
force_document_filtersint[]Ids of the enforced document verification filters.
blocked_gatewaysstring[]Keys of the payment methods closed to this client.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/security-settings' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"block_proxy":true,"blocked_gateways":["PayPal"]}'
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/security-settings', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ block_proxy: true, blocked_gateways: ['PayPal'] }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/security-settings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'block_proxy'      => true,
        'blocked_gateways' => ['PayPal'],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$response = Api::Clients()->UpdateClientSecuritySettings([
    'id'          => 42,
    'block_proxy' => true,
]);

Support Settings

patch/api/v1/admin/clients/{id}/support-settings
Clients/UpdateClientSupportSettings admin

Restricts or closes the client's ability to open support tickets.

Body 2
ticket_restrictedboolRestricts opening tickets.
ticket_blockedboolBlocks opening tickets outright. Works on any client. On a blacklisted client it is written together with the blacklist's block_tickets; the other restrictions are left alone.
Response fields data — 2
ticket_restrictedboolWhether opening tickets is restricted. The whole state comes back, not only the part you sent.
ticket_blockedboolWhether opening tickets is blocked. The block in force: it is also true for a client blocked only through the blacklist restriction.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/support-settings' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"ticket_restricted":true}'
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/support-settings', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ticket_restricted: true }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/support-settings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['ticket_restricted' => true]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$response = Api::Clients()->UpdateClientSupportSettings([
    'id'                => 42,
    'ticket_restricted' => true,
]);

Pitfalls

Changing the password asks for no old one

The endpoint is an operator tool: it writes a new password without knowing the current one. The flow where a client changes their own password is a different one and lives in the Client API.

Verifying sends no code

verify only sets the flag; no email or SMS reaches the client. Call it after your own verification flow has run, not instead of it.

The two proxy fields are opposites

block_proxy blocks and allow_proxy exempts. Sending both as on leaves a contradictory state; send only the one you mean.

Ήταν χρήσιμο;

Ευχαριστούμε για τα σχόλιά σας!

Χρειάζεστε ακόμη βοήθεια;

Η ομάδα υποστήριξής μας είναι διαθέσιμη όλο το εικοσιτετράωρο για οτιδήποτε δεν βρίσκετε παραπάνω.

Επικοινωνήστε μαζί μας Άνοιγμα αιτήματος

Χρησιμοποιούμε cookies για να παραμένετε συνδεδεμένοι, να θυμόμαστε τη γλώσσα και το νόμισμά σας και να βελτιώνουμε τον ιστότοπο. Πολιτική cookies