Customer Management

Create, read, update, and deactivate customer accounts, and mint or revoke the API credentials they authenticate with.

Manage the lifecycle of a customer account: create it, read and update its profile, deactivate it, and mint or revoke the API credentials it uses to call the rest of the platform. A customer is the tenant your end users live under—create it first, then generate credentials before issuing user tokens or opening wallets.

Authentication: every endpoint on this page uses a Bearer token in the Authorization header, except List Customers, which takes a master API key instead.

Authorization: Bearer YOUR_SESSION_TOKEN

All requests accept an optional x-trace-id header for request tracking; if omitted, one is generated.

Create Customer

POSThttps://api.sandbox.sovera.io/sovx/v1/customers

Register a customer account. Pass the customer_id issued upstream along with a contact email and the legal entity name—the service validates the ID, pulls the full business profile, and persists the record. The customer_id must be unique: if a customer with that ID already exists, the call fails with 409 Conflict. The response carries the full customer object.

Request Body

Field	Type	Required	Description
email	string	Yes	Primary contact email for the account (max 255).
customer_id	string	Yes	Unique identifier for the customer, issued upstream (max 48).
entity_name	string	Yes	Legal name of the business entity (max 255).

{
  "email": "[email protected]",
  "customer_id": "corp-redundant-firewall",
  "entity_name": "Hedge Fund e-commerce"
}

Success Response (201 Created):

{
  "success": true,
  "data": {
    "account_type": "corporation",
    "account_role": "client",
    "account_purpose": "Arbitrage Trading",
    "first_name": "Sean",
    "last_name": "Fox",
    "email": "[email protected]",
    "phone_country_code": "US",
    "phone_number": "631-789-8340",
    "customer_id": "sovbs-6f5d8756-e0ae-401f-9f3f-4d220a1dcbab",
    "business": {
      "entity_name": "Hedge Fund e-commerce",
      "incorporation_country": "VC",
      "incorporation_state": "Kingstown",
      "incorporation_date": "2012-11-15",
      "organization_type": "LLC",
      "business_type": "Fund Administrator",
      "registration_number": "3201LLC2023",
      "description": "crypto fund",
      "accredited_investor": true,
      "non_agent_intermediary": true,
      "principal_place_country": "US",
      "principal_place_state": "CA",
      "principal_place_address": "1234 Flower Street",
      "principal_place_city": "Los Angeles",
      "principal_place_postal_code": "90403"
    },
    "status": "VERIFIED"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "email": "[email protected]",
    "customer_id": "corp-redundant-firewall",
    "entity_name": "Hedge Fund e-commerce"
  }'

Errors: 400 missing/invalid fields · 401 invalid token · 404 customer_id not valid upstream · 409 customer_id already exists · 422 validation failed · 500 server error.

List Customers

GEThttps://api.sandbox.sovera.io/sovx/v1/customers

List every customer account, newest first, with pagination. This is the one endpoint on this page that does not use a Bearer token—it requires a master API key passed as x-master-api-key (or x-api-key).

x-master-api-key: YOUR_MASTER_API_KEY

Query Parameters

Parameter	Type	Required	Description
filter[limit]	number	No	Items per page (default: 20, max: 100).
filter[skip]	number	No	Offset.

GET https://api.sandbox.sovera.io/sovx/v1/customers?filter[limit]=20&filter[skip]=0

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "account_type": "corporation",
      "account_role": "client",
      "account_purpose": "Arbitrage Trading",
      "first_name": "Sean",
      "last_name": "Fox",
      "email": "[email protected]",
      "phone_country_code": "US",
      "phone_number": "631-789-8340",
      "customer_id": "sovbs-6f5d8756-e0ae-401f-9f3f-4d220a1dcbab",
      "business": {
        "entity_name": "Hedge Fund e-commerce",
        "incorporation_country": "VC",
        "incorporation_state": "Kingstown",
        "incorporation_date": "2012-11-15",
        "organization_type": "LLC",
        "business_type": "Fund Administrator",
        "registration_number": "3201LLC2023",
        "description": "crypto fund",
        "accredited_investor": true,
        "non_agent_intermediary": true,
        "principal_place_country": "US",
        "principal_place_state": "CA",
        "principal_place_address": "1234 Flower Street",
        "principal_place_city": "Los Angeles",
        "principal_place_postal_code": "90403"
      },
      "status": "VERIFIED"
    }
  ],
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f",
    "pagination": {
      "records": { "skip": 0, "has_next": false, "has_previous": false, "total": 1, "limit": 20 },
      "navigation": {
        "first": "/customers?filter[limit]=20&filter[skip]=0",
        "last": "/customers?filter[limit]=20&filter[skip]=0",
        "previous": null,
        "next": null
      }
    }
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/customers?filter[limit]=20&filter[skip]=0" \
  -H "x-master-api-key: YOUR_MASTER_API_KEY"

Errors: 401 missing or invalid master API key · 500 server error.

Get Customer

GEThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id

Retrieve a single customer by customer_id, including the full business profile and current status.

GET https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "account_type": "corporation",
    "account_role": "client",
    "account_purpose": "Arbitrage Trading",
    "first_name": "Sean",
    "last_name": "Fox",
    "email": "[email protected]",
    "phone_country_code": "US",
    "phone_number": "631-789-8340",
    "customer_id": "sovbs-6f5d8756-e0ae-401f-9f3f-4d220a1dcbab",
    "business": {
      "entity_name": "Hedge Fund e-commerce",
      "incorporation_country": "VC",
      "incorporation_state": "Kingstown",
      "incorporation_date": "2012-11-15",
      "organization_type": "LLC",
      "business_type": "Fund Administrator",
      "registration_number": "3201LLC2023",
      "description": "crypto fund",
      "accredited_investor": true,
      "non_agent_intermediary": true,
      "principal_place_country": "US",
      "principal_place_state": "CA",
      "principal_place_address": "1234 Flower Street",
      "principal_place_city": "Los Angeles",
      "principal_place_postal_code": "90403"
    },
    "status": "VERIFIED"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer not found · 500 server error.

Update Customer

PUThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id

Update a customer's profile. Send only the fields you want to change—omitted fields keep their current values, including the nested business object. Returns the full updated record.

The endpoint responds with 200 OK and the updated customer body. The Swagger annotation advertises 204 No Content, but the handler returns the record—document and integrate against the real 200 behavior.

Request Body

All fields are optional. Include only the fields you want to change.

Field	Type	Required	Description
account_type	string	No	Account type. One of `individual`, `corporation`.
account_role	string	No	Account role. One of `client`, `partner`.
account_purpose	string	No	Primary purpose or use case for the account.
first_name	string	No	First name of the account holder.
last_name	string	No	Last name of the account holder.
email	string	No	Primary email address.
phone_country_code	string	No	Country code for the phone number (ISO 3166-1 alpha-2).
phone_number	string	No	Phone number for the account.
business	object	No	Business entity information (see below).

`business` object

All fields optional except entity_name and incorporation_country, which are required when business is present.

Field	Type	Required	Description
entity_name	string	Yes	Legal name of the business entity (max 255).
incorporation_country	string	Yes	Country of incorporation (ISO 3166-1 alpha-2).
incorporation_state	string	No	State or province of incorporation.
incorporation_date	string	No	Incorporation date (`YYYY-MM-DD`).
organization_type	string	No	Legal structure (LLC, Corp, etc.).
business_type	string	No	Type of business activity or industry.
registration_number	string	No	Business registration or license number.
description	string	No	Brief description of the business activities.
accredited_investor	boolean	No	Whether the entity is an accredited investor.
non_agent_intermediary	boolean	No	Whether the entity is a non-agent intermediary.
principal_place_country	string	No	Country of the principal place of business.
principal_place_state	string	No	State or province of the principal place of business.
principal_place_address	string	No	Street address of the principal place of business.
principal_place_city	string	No	City of the principal place of business.
principal_place_postal_code	string	No	Postal code of the principal place of business.

{
  "account_purpose": "Arbitrage Trading",
  "phone_number": "408-721-7741",
  "business": {
    "entity_name": "Hedge Fund e-commerce",
    "incorporation_country": "US",
    "organization_type": "LLC"
  }
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "account_type": "corporation",
    "account_role": "client",
    "account_purpose": "Arbitrage Trading",
    "first_name": "Sean",
    "last_name": "Fox",
    "email": "[email protected]",
    "phone_country_code": "US",
    "phone_number": "408-721-7741",
    "customer_id": "sovbs-6f5d8756-e0ae-401f-9f3f-4d220a1dcbab",
    "business": {
      "entity_name": "Hedge Fund e-commerce",
      "incorporation_country": "US",
      "incorporation_state": "Kingstown",
      "incorporation_date": "2012-11-15",
      "organization_type": "LLC",
      "business_type": "Fund Administrator",
      "registration_number": "3201LLC2023",
      "description": "crypto fund",
      "accredited_investor": true,
      "non_agent_intermediary": true,
      "principal_place_country": "US",
      "principal_place_state": "CA",
      "principal_place_address": "1234 Flower Street",
      "principal_place_city": "Los Angeles",
      "principal_place_postal_code": "90403"
    },
    "status": "VERIFIED"
  },
  "meta": {
    "timestamp": "2026-01-15T12:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X PUT "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -d '{
    "account_purpose": "Arbitrage Trading",
    "phone_number": "408-721-7741",
    "business": {
      "entity_name": "Hedge Fund e-commerce",
      "incorporation_country": "US",
      "organization_type": "LLC"
    }
  }'

Errors: 400 invalid format · 401 invalid token · 404 customer not found · 409 conflict · 422 validation failed · 500 server error.

Delete Customer

DELETEhttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id

Soft-delete a customer. The record is marked inactive but never erased, and every credential belonging to that customer is deactivated in the same call—so any API key under it stops working immediately.

DELETE https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}

Success Response (204 No Content) — empty body, no JSON.

curl -X DELETE "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer not found · 500 server error.

Generate Credentials

POSThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/credentials

Mint a fresh API key for a customer. There's no request body—the service generates the key upstream and records an owner credential. The response carries the customer_secret in clear text once; store it securely, because every later read masks it.

POST https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/credentials

No request body.

Success Response (201 Created):

{
  "success": true,
  "data": {
    "customer_id": "corp-redundant-firewall",
    "customer_secret": "uiFkvaYbt1YfBO2NiXyi1txbdysIxa8H"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/credentials" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer not found · 500 server error.

List Credentials

GEThttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/credentials

List every credential issued to a customer. API keys are masked—only a short prefix is shown, followed by an ellipsis (...); the rest of the secret isn't returned—so you can identify a key without exposing it.

GET https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/credentials

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "credential_id": "a3f1c2d4-5e6f-7081-92a3-b4c5d6e7f809",
      "customer_id": "sovbs-6f5d8756-e0ae-401f-9f3f-4d220a1dcbab",
      "customer_secret": "uiFkvaYbt1...",
      "is_owner": true,
      "user_email": "[email protected]",
      "user_name": "Hedge Fund e-commerce",
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z",
      "is_active": true
    }
  ],
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/credentials" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 customer not found · 500 server error.

Delete Credential

DELETEhttps://api.sandbox.sovera.io/sovx/v1/customers/:customer_id/credentials/:credential_id

Deactivate a single credential by its credential_id. The key stops working immediately; other credentials under the same customer are untouched.

DELETE https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/credentials/{{credentialID}}

Success Response (204 No Content) — empty body, no JSON.

curl -X DELETE "https://api.sandbox.sovera.io/sovx/v1/customers/{{customerID}}/credentials/{{credentialID}}" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Errors: 401 invalid token · 404 credential not found · 500 server error.

Customer Management

On this page