{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"dcadc288-9c6e-435c-8dc5-4758d245472f","name":"Apicbase API","description":"# This documentation is now unsupported and no longer updated!\n\nThese legacy docs are still available here, but new and up-to-date information can be found at our new developer hub at [developers.apicbase.com](https://developers.apicbase.com).\n\n---\n\n# Introduction\n\nThe Apicbase API uses version 2.0 of the **OAuth** specification for authentication and authorization. This means that all requests will need to be encrypted and sent via HTTPS.\n\nIs this your first time connecting to the Apicbase API? Are you not familiar with OAuth? Take a look at [the quick start guide](https://support.apicbase.com/en/help/api-auth-step-by-step-guide) in our knowledge base to help you get started.\n\n## Endpoints\n\nThe API is accessed by making HTTP requests to an endpoint URL. Most GET endpoints accept parameters that allow you to specify which information you wish to access. Calls to the API must be made via an SSL-enabled HTTPS (port 443), as per the OAuth 2.0 specification.\n\nThe base URL for every HTTP endpoint for the current version is `https://app.apicbase.com/api/v1/`\n\n## The OAuth Specification\n\nThis API exclusively uses the Authorization Code grant of the OAuth framework for authorization. A comprehensive guide to the Authorization Code flow can be found [here](https://oauth.net/2/grant-types/authorization-code/).\n\n## Support\n\nDo you have questions about the API? Contact us directly at [api_support@apicbase.com](mailto:api_support@apicbase.com) to receive specialised support. When you describe a potential issue, please provide the maximum amount of details possible, and include both the raw request and response.\n\n# Authentication and Authorization\n\n## Registering an application\n\nEvery party accessing the API must be registered as an application.\n\nLibrary owners can create an application for themselves through the Apicbase user interface. This option can be found in [your library settings page](https://app.apicbase.com/settings/library_settings/). You must have the API module in order to use API functionalities -- contact us at [sales@apicbase.com](mailto:sales@apicbase.com) to add this module to your account.\n\nThird parties must obtain those credentials directly from us. Contact us first at [sales@apicbase.com](mailto:sales@apicbase.com) if you are a third party that wishes to interact with customer data through the Apicbase API.\n\n## Generating an access token\n\nThe [the quick start guide](https://support.apicbase.com/en/help/api-auth-step-by-step-guide) at our knowledge base contains detailed instructions on how to generate an access token and authorize your client into our API for the first time.\n\nUse your client credentials to generate an access token.\n\nThe authorization URL is `https://app.apicbase.com/oauth/authorize/`. A sample valid url will therefore look like `https://app.apicbase.com/oauth/authorize/?response_type=code&client_id=MY_CLIENT_ID&scope=SCOPE1+SCOPE2`.\n\nThe access token URL is `https://app.apicbase.com/oauth/token/`. With the authentication code obtained from the authorization URL, make a POST request to this URL with the following payload:\n\n```\ngrant_type=\"authorization_code\",\ncode=\"YOUR_AUTHORIZATION_CODE\",\nredirect_uri=\"YOUR_REDIRECT_URI\",\nclient_id=\"YOUR_CLIENT_ID\",\nclient_secret=\"YOUR_CLIENT_SECRET\"\n\n```\n\nPOST requests to the `oauth/token` endpoint must be encoded as **x-www-form-urlencoded**.\n\nYou may opt for sending your client's credentials in the Authorization header as Basic authentication. This also works. In this case, you can omit the `client_id` and the `client_secret` from the payload.\n\nThe authorization server will reply with an access token and a refresh token, as well as the allowed scopes and the expiration time (in seconds).\n\n## Using the access token\n\nThe access token is used to both authenticate (tell Apicbase which library you're connecting to) and authorize (verify that you have the required permissions) your client. Include the access token in the Authorization header with each request, like so:\n\n``` bash\ncurl --location \\\n--request GET 'https://app.apicbase.com/api/v1/outlets/' \\\n--header 'Authorization: Bearer {YOUR ACCESS TOKEN}'\n\n```\n\nAn access token is tied to a library, so all actions will be performed in the library that the token you're using is tied to.\n\nAs a third party, you must keep track of which libraries your tokens belong to.\n\n## Requesting a new token\n\nThe access token expires automatically after some time. You might get a `401 Unauthorized` if you're using an expired token. When that happens, request a new token using the refresh token by making a new POST request to the token endpoint:\n\n``` bash\ncurl -X POST \\\n -d \"grant_type=refresh_token&client_id=MY_CLIENT_ID&client_secret=MY_CLIENT_SECRET&refresh_token=MY_REFRESH_TOKEN\" \\\nhttps://app.apicbase.com/oauth/token/\n\n```\n\nThe server will reply with a new set of access and refresh tokens. The old pair will be invalidated.\n\n## Introspecting a token\n\nYour client can make requests to `https://app.apicbase.com/oauth/introspect/` in order to check the validity of an access token. Include the token along with your client credentials in a GET request:\n\n``` bash\ncurl --location \\\n--request GET 'https://app.apicbase.com/oauth/introspect/?token=MY_ACCESS_TOKEN&client_id=MY_CLIENT_ID&client_secret=MY_CLIENT_SECRET'\n\n```\n\nOr in a POST request, with those same parameters in the request body:\n\n``` bash\ncurl -X POST -d \"token=MY_ACCESS_TOKEN&client_id=MY_CLIENT_ID&client_secret=MY_CLIENT_SECRET&refresh_token=MY_REFRESH_TOKEN\" \\\nhttps://app.apicbase.com/oauth/introspect/\n\n```\n\nIf the token is valid, belongs to the authenticated client and is not expired, the server will reply with information about the token:\n\n``` json\n{\n    \"active\": true,\n    \"scope\": \"library sales accounts procurement\",\n    \"exp\": 1613120953,\n    \"client_id\": \"MY_CLIENT_ID\",\n    \"username\": \"john.doe@apicbase.com\"\n}\n\n```\n\nThe `exp` field contains a unix timestamp which represents the expiration date of the token. This response means that the token is valid and can be used to interact with the API.\n\nIf the token is valid but expired, the server will reply with a `200 OK` response, but the following body:\n\n``` json\n{\n    \"active\": false\n}\n\n```\n\nThis means that your client should use the refresh token to request a new access token.\n\nIf the token is invalid or does not belong to the given client, the server will reply with a `401 Unauthorized` response.\n\n## Access scopes\n\nThe authorized scopes of your token define which endpoints it can be used to interact with. The following scopes have been defined:\n\n- `accounts`: Manage user accounts and permissions\n- `library`: View library items: ingredients, recipes, menus...\n- `procurement`: View purchase orders and delivery information of orders made through Apicbase\n- `sales`: Read and upload sales/POS data\n- `media`: View images uploaded to Apicbase\n    \n\nFor security reasons, you should only request the scopes that are necessary for your application to function. You may request multiple scopes at a time: separate them with a `+` in the authorization code URL.\n\nThe permissions of the API account your application will be used to connect also determine the level of access your client will have. For example, if the API user in the library you're connecting to doesn't have admin rights, your application will be blocked from managing accounts in that library even if you've requested the `accounts` scope.\n\n## Rate limiting\n\nIn order to maximize stability and ensure good service to all API users, the Apicbase API employs a rate limiting strategy. All API users are currently limited to **100 request per minute**. This limit applies to trial as well as full customers and third-party partners, for read and write operations. If your application exceeds this limit, the server will respond with status code `429 Too Many Requests`.\n\nAPI users should do their best to avoid getting this error (for example, by introducing a `sleep` statement between requests) or implement a retry mechanism to handle these errors gracefully.\n\nIt's common to run into this issue when `GET` endpoints (e.g. the Recipe list endpoint) are accessed in quick succession. API users should keep in mind that it is _not_ ideal to use the Apicbase API as a live API to serve real-time data about recipes, ingredients and other entities. The detail endpoints are particularly resource-intensive operations that aggregate large amounts of data to be served in a single JSON object.\n\nFor the sake of their own application flow, and in order to minimize the overhead of waiting for Apicbase to compile this data or of having requests denied by the rate limiter, clients should best employ strategies to avoid querying the Apicbase API for redundant data (i.e. unchanged since the last request) and generating unnecessary load. Customers will find the `modified_date` filter available on the list `GET` endpoints most useful for implementing such strategies.\n\nTo further help API consumers graciously handle rate limiting and avoid errors due to limits violation, we provide Rate Limiter Headers on every response from an endpoint bound by the rate limiter. The Rate Limiting Header contains three parameters:\n\n| **Rate Limiter Headers** | **Description** |\n| --- | --- |\n| X-RateLimit-Limit | Request limit per minute for the current endpoint (usually 100/minute) |\n| X-RateLimit-Remaining | The number of requests left for the current one minute rolling window |\n| X-RateLimit-Wait | When the user is rate limited, this header tells how many seconds the user must wait until the next request |\n\nBy using the information provided on the `X-RateLimit-Remaining` header, the API consumer can prevent a limit violation by not exceeding the number of requests left from the moment the response was received up to one minute after that.\n\nIn case a violation of the limit incurs and a `429 Too Many Requests` is received, the API consumer can retrieve from the `X-RateLimit-Wait` header of the 429 response the amount of seconds it must wait before making the next request, in order to prevent further 429 responses.\n\nThe pseudo-python code below constitutes a routine that continuously fetches information from the `/xyz` endpoint at the limit allowed by the rate limiter. This routine demonstrates the use of both the `X-RateLimit-Remaining` and `X-RateLimit-Wait`.\n\n``` python\nwhile True:\n    requests_left = 1\n    while requests_left > 0:\n        response = request.get('apicbase.com/xyz')\n        requests_left = response.headers['X-RateLimit-Remaining']\n        do_something_with_the_(response)\n    wait_time = response.headers['X-RateLimit-Wait']\n    time.sleep(wait_time)\n\n```\n\n---","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"1341785","team":1133642,"collectionId":"dcadc288-9c6e-435c-8dc5-4758d245472f","publishedId":"2s8Z6vaFEo","public":true,"publicUrl":"https://api-legacy.apicbase.com","privateUrl":"https://go.postman.co/documentation/1341785-dcadc288-9c6e-435c-8dc5-4758d245472f","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2023-05-03T11:59:15.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/761b1b50b606f35184b4a9da14f8f715ac2943ffa20eff42fb8ea87455155bc6","favicon":"https://res.cloudinary.com/postman/image/upload/v1653985646/team/exccklhy9z49ivuhlxtf.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://api-legacy.apicbase.com/view/metadata/2s8Z6vaFEo"}