{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-openapi.json","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"openapi.json","settings":{"baseUrlPath":"/openapi"},"disableAutoScroll":true,"seo":{"title":"External Developer Portal API","llmstxt":{"hide":true}},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"External Developer Portal API","version":"v1","description":"# Introduction\r\n\r\nSustainability Master is a B2B SaaS solution for ESG management, hosted on Microsoft Azure Cloud in Europe.\r\n\r\nThe solution is data-driven, with more than a thousand data points that can be imported, processed and exported. Data can be exchanged by uploading predefined templates, through form entry by business users, or through the predefined APIs in the Sustainability Master API Portal (SMAP).\r\n\r\nThis portal helps authorized developers at customer and partner companies connect to the SMAP APIs.\r\n\r\nSustainability Master APIs are **REST** APIs. They let you perform RESTful operations such as reading, adding, modifying and deleting data.\r\n\r\n# Getting started\r\n\r\n## Configure an environment\r\n\r\nTo send requests from this portal, set up an environment with your server URL and API Secret.\r\n\r\n1. Open any endpoint in the API reference and select **Try it** in the request sample panel.\r\n\r\n   ![Try it button on an endpoint page](./images/any%20api_Try%20it.png)\r\n\r\n2. In the API console, select the **Configure environments** icon in the top-right corner.\r\n\r\n   ![Configure environments option](./images/Configure%20environment_option.png)\r\n\r\n3. In the **Environments** panel, select **New environment**, then:\r\n   - Give the environment a name (for example, `DEV` or `QA`).\r\n   - Set the **server** base URL.\r\n   - Under **Inputs**, enter your API Secret in the **Bearer** input's **Value** field and turn on **Secret** so the key stays masked.\r\n\r\n   ![New environment with Bearer secret input](./images/New_environment.png)\r\n\r\n4. Select the environment so it shows as **Active**, then send your request.\r\n\r\n\r\n### Authentication Method: API Secret\r\n\r\nThe API uses an **API Secret** to authenticate requests. Every client application must send a valid API Secret in the request headers.\r\n\r\n### Obtaining an API Secret\r\n\r\n**Generating an API Key:** Request an API key through the Sustainability Master interface. The system generates a unique key for you.\r\n\r\n**Refreshing an API Key:** When a key needs to be updated, generate a new one. It replaces the old key so access continues without interruption.\r\n\r\n**Authenticating API Requests**\r\n\r\nOnce you have an API Secret, include it in the `Authorization` header of your API requests:\r\n\r\n```http\r\nGET /api/ConnectionCheck/EchoTest HTTP/1.1\r\nHost: <your-server>\r\nAuthorization: YOUR_API_SECRET\r\nContent-Type: application/json\r\n```\r\n\r\nUse the **Connection Check › Echo test** endpoint to confirm that your API Secret works.\r\n\r\n## Security Best Practices\r\n\r\nTo protect your API Secret and maintain security, follow these best practices:\r\n\r\n- **Keep your API Secret confidential:** Don't share it in public forums or code repositories.\r\n- **Rotate API Secrets periodically:** Generate new secrets regularly and retire old ones.\r\n- **Use secure storage:** Store API Secrets in environment variables or a secure vault.\r\n- **Limit access:** Give secrets only to authorized applications and users.\r\n- **Monitor API usage:** Track API calls so you can detect unauthorized access.\r\n\r\n**Error Responses**\r\n\r\nIf an invalid or missing API Secret is detected, the API returns a `401 Unauthorized` error.\r\n\r\n**Revoking and Regenerating API Secrets**\r\n\r\nIf you suspect your API Secret has been compromised, revoke it and generate a new one in the Configurator, under **API Keys**.\r\n\r\n## Errors\r\n\r\n| HTTP status | Applicable |\r\n|---|---|\r\n| 400 | Yes |\r\n| 401 | Yes |\r\n| 402 | No |\r\n| 403 | No |\r\n| 404 | Yes |\r\n| 405 | Yes |\r\n| 406 | Yes |\r\n| 415 | Yes |\r\n| 429 | Yes |\r\n| 500 | Yes |\r\n\r\n## Error codes\r\n\r\n| HTTP status | Code | Message |\r\n|---|---|---|\r\n| 400 | Validation error | The request body or query string is not in the correct format. |\r\n| 401 Unauthorized | Invalid secret | The API Secret provided is invalid or missing. |\r\n| 403 Forbidden | Access denied | The API Secret does not have permission to access the requested resource. |\r\n| 404 | Requested resource not found | The request contains an invalid ID or domain in the URL, or the URL itself is invalid. |\r\n| 405 | Method not allowed | The request used the wrong HTTP method. |\r\n| 406 | Unsupported Accept header | Only `application/json` and `*/*` are supported. File uploads support `multipart/form-data`. |\r\n| 415 | Unsupported content type | `application/xml` is not supported. Only `application/json` is supported. |\r\n| 500 | Unexpected server error | An internal server error occurred. |\r\n\r\n| Code | Description |\r\n|---|---|\r\n| `invalid_value` | The request contained an incorrect or blank value, or a value in an invalid format. |\r\n| `duplicate_value` | The value already exists. Applies to fields that must be unique, such as a contact's email address or a company name. |\r\n\r\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"developer.sustainabilitymaster.ai","port":4000,"ipAddress":"216.73.216.253"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/openapi","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}