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
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | Account |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "account",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"name": "string",
"email": "[email protected]",
"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
| Name | Type | Required | Description |
|---|
Idempotency-Key | string | no | Makes 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
| Field | Type | Required | Description |
|---|
name | string | no | ≤ 255 chars |
first_name | string | no | ≤ 100 chars |
last_name | string | no | ≤ 100 chars |
netopia_api_key | string | no | ≤ 4096 chars |
netopia_pos_signature | string | no | ≤ 255 chars |
Example request
{
"name": "string",
"first_name": "string",
"last_name": "string",
"netopia_api_key": "string",
"netopia_pos_signature": "string"
}
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | Account |
| 400 | Invalid body or no fields to update. | validation_failed invalid_json empty_update |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server error. | api_error |
Example response
{
"object": "account",
"id": "01JB9XK3M2R7TQ8N4V6Y0ZPA1C",
"name": "string",
"email": "[email protected]",
"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
| Name | Type | Required | Description |
|---|
Idempotency-Key | string | no | Makes 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)
| Field | Type | Required | Description |
|---|
name | string | no | default "Default key" |
Example request
{
"name": "Default key"
}
Responses
| Status | Meaning | Body / error codes |
|---|
| 201 | Key created. | ApiKeyWithSecret |
| 400 | Invalid body. | validation_failed invalid_json |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server 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
| Name | Type | Required | Description |
|---|
keyId | string | yes | API key ID · 26 chars |
Headers
| Name | Type | Required | Description |
|---|
Idempotency-Key | string | no | Makes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars |
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | ApiKey |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server 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
| Name | Type | Required | Description |
|---|
keyId | string | yes | API key ID · 26 chars |
Headers
| Name | Type | Required | Description |
|---|
Idempotency-Key | string | no | Makes retries safe: same key + body replays the stored response (idempotency-replayed: true); a different body returns 409 idempotency_key_in_use. · ≤ 96 chars |
Responses
| Status | Meaning | Body / error codes |
|---|
| 200 | Success. | ApiKeyWithSecret |
| 401 | Missing or invalid API key. | authentication_error |
| 404 | Not found, or not yours. | resource_missing |
| 429 | Rate limited; honor retry-after. | rate_limit_exceeded too_many_auth_failures |
| 500 | Server 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"
}