{ "openapi": "3.1.0", "info": { "title": "NOCCIE API", "version": "0.1.0", "description": "Machine access to NOCCIE with tenant API keys. A tenant administrator creates an API key. Your integration exchanges the key for a short-lived bearer token (OAuth 2.0 client credentials) and uses that token on the endpoints listed here. See the [authentication guide](/api/getting-started)." }, "servers": [ { "url": "https://api.noccie.app", "description": "Public NOCCIE API." } ], "tags": [ { "name": "Authentication", "description": "Exchange an API key for an access token." }, { "name": "Products", "description": "Read the product catalog of a tenant." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/oauth/token": { "post": { "tags": [ "Authentication" ], "operationId": "createToken", "summary": "Request an access token", "description": "Exchanges an API key (client id and client secret) for a bearer token with the OAuth 2.0 `client_credentials` grant.\n\nSend the credentials in one of three ways: as a JSON body, as an `application/x-www-form-urlencoded` body, or as an HTTP Basic `Authorization` header. `grant_type` is required in the body in every case. If you use the Basic header, either leave the credentials out of the body or send exactly the same `client_id` and `client_secret`. Otherwise the request is rejected with `invalid_request`.\n\nThe token is valid for one hour (`expires_in` is `3600`). Cache it and request a new one shortly before it expires. The token does not contain the key's scopes: they are checked on every request, so revoking a key or changing its scopes takes effect immediately.\n\nThe endpoint is rate limited, per client IP address and per key. Cache your token instead of requesting a new one for every call.", "security": [ { "basicAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" }, "example": { "grant_type": "client_credentials", "client_id": "tk_EXAMPLEEXAMPLEEXAMPLEEXAMPLE00", "client_secret": "example-client-secret-not-real" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "The access token.", "headers": { "Cache-Control": { "description": "Always `no-store`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "example": { "access_token": "eyJhbGciOi...example", "token_type": "Bearer", "expires_in": 3600, "scope": "view_product", "tenant_id": "00000000-0000-0000-0000-000000000000" } } } }, "400": { "description": "The request is malformed (`invalid_request`) or the grant type is not `client_credentials` (`unsupported_grant_type`). Missing or badly formatted credentials, a malformed Basic header and a body that does not exactly match the Basic header (`client_id` and `client_secret`) are all `invalid_request`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "examples": { "invalid_request": { "value": { "error": "invalid_request" } }, "unsupported_grant_type": { "value": { "error": "unsupported_grant_type" } } } } } }, "401": { "description": "The credentials are not accepted. The response is identical for an unknown key, a wrong secret, a revoked key and an expired key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "invalid_client" } } } }, "429": { "description": "Too many token requests. Wait and retry, and cache your token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "rate_limited" } } } }, "500": { "description": "Temporary server error. Retry later. The service can also return this body with status 502.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "server_error" } } } } } } }, "/tenant/{tenantid}/product": { "get": { "tags": [ "Products" ], "operationId": "listProducts", "summary": "List products", "description": "Returns the products of a tenant. The key must have the `view_product` scope, and `tenantid` must be the tenant the key belongs to.\n\nAll query parameters are optional filters. Each takes a single value or a comma-separated list, for example `type=service,set`. A parameter other than `id`, `type` and `category`, a repeated parameter, or a value that is too long or contains other characters than letters, digits, `_`, `-` and `,` is rejected with `400 invalid_request`.\n\nCost prices are never included in the response.", "x-required-scope": "view_product", "parameters": [ { "name": "tenantid", "in": "path", "required": true, "description": "The tenant id of the API key.", "schema": { "type": "string", "format": "uuid" }, "example": "00000000-0000-4000-8000-000000000001" }, { "name": "id", "in": "query", "required": false, "description": "Product id, or a comma-separated list of product ids.", "schema": { "type": "string", "maxLength": 4000, "pattern": "^[A-Za-z0-9_,-]*$" }, "example": "00000000-0000-4000-8000-000000000001" }, { "name": "type", "in": "query", "required": false, "description": "Product type, or a comma-separated list of types.", "schema": { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9_,-]*$" }, "example": "service,set" }, { "name": "category", "in": "query", "required": false, "description": "Category id, or a comma-separated list of category ids.", "schema": { "type": "string", "maxLength": 4000, "pattern": "^[A-Za-z0-9_,-]*$" }, "example": "00000000-0000-4000-8000-000000000002" } ], "responses": { "200": { "description": "The matching products. An empty list when nothing matches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" }, "example": { "products": [ { "id": "00000000-0000-4000-8000-000000000001", "tenant": "00000000-0000-4000-8000-0000000000aa", "name": "Example product", "category": "00000000-0000-4000-8000-000000000002", "price_rental": "12.50", "vat_id": "00000000-0000-4000-8000-000000000003", "type": "service", "stock_type": "none", "account_code_rental": null, "account_code_sales": null, "price_sales": "25.00", "price_missing": null, "allow_rental": true, "allow_sales": true, "daily_increase_factor_group": null, "disable_daily_increase_factor": false, "has_stock": false, "info": {} } ] } } } }, "400": { "description": "A query parameter is not allowed or has an invalid value. `issues` (usually present) lists where (path) and why (code), never the submitted values. A request with an invalid URL returns only `error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "error": "invalid_request", "issues": [ { "path": [ "query" ], "code": "unrecognized_keys" }, { "path": [ "query", "type" ], "code": "too_big" } ] } } } }, "401": { "description": "The token is missing, invalid, expired, belongs to a revoked or expired key, or belongs to a different tenant than `tenantid`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "code": "invalid_request", "message": "invalid_request" } } } }, "403": { "description": "The route or the required scope is not permitted for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "success": false, "code": "not_allowed", "message": "not_allowed" } } } } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic with the key id as username and the key secret as password. Only used on the token endpoint, as an alternative to sending the credentials in the body." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The `access_token` from `POST /oauth/token`, sent as `Authorization: Bearer `. Valid for one hour." } }, "schemas": { "TokenRequest": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Always `client_credentials`. Required, also when you use the Basic header." }, "client_id": { "type": "string", "pattern": "^tk_[A-Za-z0-9_-]{20,128}$", "description": "The key id, starts with `tk_`. Required unless you use the Basic header.", "example": "tk_EXAMPLEEXAMPLEEXAMPLEEXAMPLE00" }, "client_secret": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The key secret, shown once when the key was created. Required unless you use the Basic header.", "example": "example-client-secret-not-real" } } }, "TokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope", "tenant_id" ], "properties": { "access_token": { "type": "string", "description": "A signed JWT. Treat it as an opaque string." }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Lifetime in seconds. Always `3600`.", "example": 3600 }, "scope": { "type": "string", "description": "The scopes of the key at the time of issuing, separated by spaces. Informational: scopes are checked live on every request.", "example": "view_product" }, "tenant_id": { "type": "string", "format": "uuid", "description": "The id of the tenant the key belongs to. Use it in the path of every call: `/tenant/{tenant_id}/...`.", "example": "00000000-0000-0000-0000-000000000000" } } }, "OAuthError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_request", "unsupported_grant_type", "invalid_client", "rate_limited", "server_error" ] } } }, "ValidationError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_request" ] }, "issues": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "path", "code" ], "properties": { "path": { "type": "array", "description": "Where the problem is, for example `[\"query\", \"type\"]`.", "items": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } }, "code": { "type": "string", "description": "A short machine-readable reason, for example `too_big` or `invalid_format`." } } }, "description": "Present for invalid query parameters; may be absent." } } }, "ProductList": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "Product": { "type": "object", "description": "A product. Cost prices are not included. Amounts are decimal numbers in a string, for example `\"12.50\"`.", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "format": "uuid" }, "type": { "type": [ "string", "null" ], "description": "Product type, for example `service` or `set`." }, "stock_type": { "type": "string", "description": "For example `none` or `barcode`." }, "has_stock": { "type": "boolean", "description": "`true` unless `stock_type` is `none`." }, "price_rental": { "type": [ "string", "null" ], "description": "Rental price, decimal in a string." }, "price_sales": { "type": [ "string", "null" ], "description": "Sales price, decimal in a string." }, "price_missing": { "type": [ "string", "null" ], "description": "Price charged when an item is missing, decimal in a string." }, "vat_id": { "type": [ "string", "null" ], "format": "uuid" }, "account_code_rental": { "type": [ "string", "null" ], "format": "uuid" }, "account_code_sales": { "type": [ "string", "null" ], "format": "uuid" }, "allow_rental": { "type": "boolean" }, "allow_sales": { "type": "boolean" }, "daily_increase_factor_group": { "type": [ "string", "null" ], "format": "uuid" }, "disable_daily_increase_factor": { "type": [ "boolean", "null" ] }, "info": { "type": "object", "additionalProperties": true, "description": "Additional product fields, configured per tenant. The keys differ per tenant." }, "thumbnail_url": { "type": "string", "format": "uri", "description": "Signed link to the thumbnail. Only present when the product has a thumbnail. The link expires." }, "barcodes": { "type": "array", "description": "Only present when `stock_type` is `barcode`.", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "format": "uuid" }, "barcode": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "blocked": { "type": "boolean" } } } }, "items": { "type": "array", "description": "Only present when `type` is `set`: the components of the set.", "items": { "type": "object", "additionalProperties": true, "properties": { "parent": { "type": "string", "format": "uuid" }, "child": { "type": "string", "format": "uuid" }, "quantity": { "type": "string", "description": "Decimal in a string." } } } } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "code": { "type": "string", "description": "For example `invalid_request` (401) or `not_allowed` (403)." }, "message": { "type": "string" } } } } } }