vsmsconnect — API — api-keys

← all endpoints

POST/api/v1/businesses/:businessId/api-keys auth: jwt (administrator)

Generate a new static API key for on-premise agents (Sage 100/300/200 Evolution, Amicus). Stores SHA-256(rawKey) + an 8-char prefix; returns the raw 64-hex-char key exactly once. Optional scope binds the key to one AccountingProviderType; optional locationId scopes it to one Location (validated against the business). Fires API_KEY_CREATED.

handlers: ApiKeyController.create

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID. Administrator bypass via requireBusinessAccess.
label body
string		yes—Operator-facing label (1..200 chars).
scope body
AccountingProviderType		no—Bind to a single provider (sage100, sage300, sage200evolution, amicus, ...). Null/omitted = unscoped.
locationId body
uuid		no—Multi-location (TAXCORE-246) — scope the key to one Location. Validated against the business; mismatch returns 422 LOCATION_NOT_FOUND.

Outputs

201
APIResponseDataObject<CreateApiKeyResponse>
ApiKeyDTO plus the raw `key` (64 hex chars). The raw key is shown ONCE and never returned again.
403
APIError
USER_FORBIDDEN — not Administrator or businessId mismatch.
422
APIError
LOCATION_NOT_FOUND — locationId does not belong to this business. VALIDATION_ERROR — schema violation.
GET/api/v1/businesses/:businessId/api-keys auth: jwt (administrator)

List all API keys for a business (active + revoked). Raw secret is never returned — only label, prefix, scope, locationId, createdAt, lastUsedAt, revokedAt.

handlers: ApiKeyController.list

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.

Outputs

200
APIResponseDataList<ApiKeyDTO>
All API keys (active and revoked) for the business.
403
APIError
USER_FORBIDDEN — not Administrator or businessId mismatch.
DELETE/api/v1/businesses/:businessId/api-keys/:keyId auth: jwt (administrator)

Soft-revoke an API key (sets RevokedAt). Idempotent — re-calling on an already-revoked key is a no-op. Fires API_KEY_REVOKED on first revocation.

handlers: ApiKeyController.revoke

Inputs

namerequireddefaultdescription
businessId path
uuid		yes—Target business UUID.
keyId path
uuid		yes—ApiKeys.ApiKeyId to revoke.

Outputs

204
void
Key revoked (or already-revoked).
403
APIError
USER_FORBIDDEN — not Administrator or businessId mismatch.
404
APIError
API_KEY_NOT_FOUND — keyId not in this business.