API reference navigation

Customer OAuth Clients

Admin

Customer OAuth Clients groups 3 operations on the admin tier.

Admin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

GET

/api/{version}/admin/oauth_clients

All clients for the tenant, newest first (including disabled ones, marked by disabled_at).

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Responses

200OAuthClientListResponseOK

curl -X GET \
  'https://<your-shop-domain>/api/2026-04-01/admin/oauth_clients' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>'

Response200example shape

{
  "oauth_clients": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "display_name": "string",
      "redirect_uris": [
        "string"
      ],
      "allowed_scopes": [
        "string"
      ],
      "allow_password_grant": true,
      "created_at": "2026-04-01T12:00:00Z",
      "disabled_at": "2026-04-01T12:00:00Z"
    }
  ]
}

POST

/api/{version}/admin/oauth_clients

Register a public client for the current tenant. Returns the public client_id; there is no secret to return. A PKCE client (the default) must register at least one absolute redirect_uri; a password-grant client may register none, since the ROPC grant performs no redirect. A missing body, a relative or malformed redirect URI and an unknown scope are all 422.

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Request body

application/json, text/json, application/*+json · optional

CreateOAuthClientRequest

Body for POST /api/{version}/admin/oauth_clients.

displayNamestringnullable
redirectUrisstring[]nullable
allowedScopesstring[]nullable
allowPasswordGrantboolean

Responses

201OAuthClientResponseCreated
422ApiErrorResponseUnprocessable Content

curl -X POST \
  'https://<your-shop-domain>/api/2026-04-01/admin/oauth_clients' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "displayName": "string",
  "redirectUris": [
    "string"
  ],
  "allowedScopes": [
    "string"
  ],
  "allowPasswordGrant": true
}'

Response201example shape

{
  "oauth_client": {
    "id": "00000000-0000-0000-0000-000000000000",
    "display_name": "string",
    "redirect_uris": [
      "string"
    ],
    "allowed_scopes": [
      "string"
    ],
    "allow_password_grant": true,
    "created_at": "2026-04-01T12:00:00Z",
    "disabled_at": "2026-04-01T12:00:00Z"
  }
}

DELETE

/api/{version}/admin/oauth_clients/{id}

Disable a client (soft — sets DisabledAtUtc). Tenant-scoped: one shop cannot disable another's client. Idempotent on a missing/already-disabled client → 404 (nothing further to disable).

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Path parameters

Name	Type	Description
id required	string (uuid)

Responses

204No Content
404ApiErrorResponseNot Found

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/admin/oauth_clients/<id>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>'

Schemas

ApiErrorResponse

The error envelope every non-2xx response from this API uses. Documentation shape: actions build it as an anonymous object, so this type exists to give the OpenAPI document a schema to point at.

errorsstringnullable
Human-readable description of what went wrong, e.g. Not Found, Invalid page_info.
codestringnullable
Machine-readable error code. Only a few endpoints (checkout) emit one; omitted everywhere else.

CreateOAuthClientRequest

Body for POST /api/{version}/admin/oauth_clients.

displayNamestringnullable
redirectUrisstring[]nullable
allowedScopesstring[]nullable
allowPasswordGrantboolean

OAuthClientDto

A registered public OAuth client of the Customer Account API. There is no secret in this representation because a public client has none — PKCE replaces it — so nothing here is confidential and the same shape is returned by both the create and the list read.

idstring (uuid)
The public client_id: the value a storefront sends as client_id to customer/auth/authorize and customer/auth/token. Note the wire name is id.
display_namestringnullable
Human-readable name for the admin surface; not used by any OAuth flow.
redirect_urisstring[]nullable
The exact-match redirect-URI allowlist, split out of its stored newline-delimited form. An authorize request whose redirect_uri is not character-for-character one of these is refused — there is no prefix or substring matching. Always present, and legitimately empty for a client that only uses the password grant, which performs no redirect.
allowed_scopesstring[]nullable
The customer/* scopes this client may request, split out of their stored space-delimited form. A token request for anything outside this set is refused.
allow_password_grantboolean
Whether the OAuth2 ROPC password grant is enabled for this client. true means the shopper's password is transmitted to the API, so it is only ever set for trusted first-party clients.
created_atstring (date-time)
When the client was registered (UTC).
disabled_atstring (date-time)nullable
When the client was disabled (UTC), or null while it is active — this is how a list row's state is read, since disabled clients stay listed. An always-present key: an active client sends an explicit null.

OAuthClientListResponse

Envelope returned by GET /admin/oauth_clients. Unpaged: there is no Link header and no page_info.

oauth_clientsOAuthClientDto[]nullable
The tenant's clients, newest first, including disabled ones — check disabled_at rather than assuming every row is usable. Always present; an empty array when none are registered.

OAuthClientResponse

Envelope returned by POST /admin/oauth_clients (201).

oauth_clientOAuthClientDto