Developer docs v0.1.0

Account

Your own account and API keys.

GET /v1/account

Retrieve your account

Your own account, identified by the API key you call with. There is no account ID in the path, so no other merchant's account is addressable.

Authentication
Merchant API key
Effect
Read-only.

Responses

StatusMeaningBody / error codes
200Success.Account
401Missing or invalid API key.authentication_error
404Not found, or not yours.resource_missing
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "account",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "name": "string",
  "email": "ana@example.com",
  "first_name": "string",
  "last_name": "string",
  "is_live": false,
  "netopia_pos_signature": "string",
  "netopia_configured": false,
  "created_at": "2026-10-25T18:00:00.000Z",
  "updated_at": "2026-10-25T18:00:00.000Z",
  "can_switch_mode": false,
  "can_sync": false
}

POST /v1/account

Update your account

Partial update.

Authentication
Merchant API key
Effect
Updates account fields; a replaced netopia_api_key is re-encrypted.

Headers

NameTypeRequiredDescription
Idempotency-KeystringnoMakes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars

Request body

FieldTypeRequiredDescription
namestringno≤ 255 chars
first_namestringno≤ 100 chars
last_namestringno≤ 100 chars
netopia_api_keystringno≤ 4096 chars
netopia_pos_signaturestringno≤ 255 chars
Example request
{
  "name": "string",
  "first_name": "string",
  "last_name": "string",
  "netopia_api_key": "string",
  "netopia_pos_signature": "string"
}

Responses

StatusMeaningBody / error codes
200Success.Account
400Invalid body or no fields to update.validation_failed invalid_json empty_update
401Missing or invalid API key.authentication_error
404Not found, or not yours.resource_missing
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "account",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "name": "string",
  "email": "ana@example.com",
  "first_name": "string",
  "last_name": "string",
  "is_live": false,
  "netopia_pos_signature": "string",
  "netopia_configured": false,
  "created_at": "2026-10-25T18:00:00.000Z",
  "updated_at": "2026-10-25T18:00:00.000Z",
  "can_switch_mode": false,
  "can_sync": false
}

POST /v1/account/keys

Create an API key

Creates an additional bearer key for your account. The secret is returned once as key; matching keyed requests can replay it.

Authentication
Merchant API key
Effect
Creates an active API key.

Headers

NameTypeRequiredDescription
Idempotency-KeystringnoMakes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars

Request body (optional)

FieldTypeRequiredDescription
namestringnodefault "Default key"
Example request
{
  "name": "Default key"
}

Responses

StatusMeaningBody / error codes
201Key created.ApiKeyWithSecret
400Invalid body.validation_failed invalid_json
401Missing or invalid API key.authentication_error
404Not found, or not yours.resource_missing
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "api_key",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "key_prefix": "string",
  "name": "string",
  "is_active": false,
  "last_used_at": "2026-10-25T18:00:00.000Z",
  "created_at": "2026-10-25T18:00:00.000Z",
  "key": "string"
}

POST /v1/account/keys/:keyId/revoke

Revoke an API key

Deactivates a key immediately. Revoked credentials stay invalid, including for idempotent replay.

Authentication
Merchant API key
Effect
Sets the key inactive.

Path parameters

NameTypeRequiredDescription
keyIdstringyesAPI key ID · 26 chars

Headers

NameTypeRequiredDescription
Idempotency-KeystringnoMakes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars

Responses

StatusMeaningBody / error codes
200Success.ApiKey
401Missing or invalid API key.authentication_error
404Not found, or not yours.resource_missing
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "api_key",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "key_prefix": "string",
  "name": "string",
  "is_active": false,
  "last_used_at": "2026-10-25T18:00:00.000Z",
  "created_at": "2026-10-25T18:00:00.000Z"
}

POST /v1/account/keys/:keyId/rotate

Rotate an API key

Revokes the key and returns a new one named "<name> (rotated)". Keep another active key available so a lost response can be recovered with the same idempotency key.

Authentication
Merchant API key
Effect
Revokes the key and creates a replacement (secret shown once).

Path parameters

NameTypeRequiredDescription
keyIdstringyesAPI key ID · 26 chars

Headers

NameTypeRequiredDescription
Idempotency-KeystringnoMakes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars

Responses

StatusMeaningBody / error codes
200Success.ApiKeyWithSecret
401Missing or invalid API key.authentication_error
404Not found, or not yours.resource_missing
429Rate limited; honor retry-after.rate_limit_exceeded too_many_auth_failures
500Server error.api_error
Example response
{
  "object": "api_key",
  "id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "merchant_id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
  "key_prefix": "string",
  "name": "string",
  "is_active": false,
  "last_used_at": "2026-10-25T18:00:00.000Z",
  "created_at": "2026-10-25T18:00:00.000Z",
  "key": "string"
}