API Endpoints
The Core component provides RESTful interfaces for external communication. These endpoints are defined by the Core Driver Interface (CDI) specification and serve as the primary interface between the Backend SDK and Core.
Overview
API Endpoints are implemented by extending the WebserverAPI class. Implementations must override the getPath method and one or more of the following methods: doGet, doPost, doPut, or doDelete.
Implementations typically utilize sendJsonResponse to return JSON responses.
Status Code Conventions
Endpoints return 200 OK status for successful API execution, including certain error scenarios.
For instance, an Email Password sign-up operation may result in either a successful registration or an email existence error. In both cases, the HTTP Status remains 200 OK. The distinction is made in the response body. A successful sign-up returns { "status": "OK", "user": ... }, while an email existence error returns { "status": "EMAIL_ALREAD_EXISTS_ERROR" }.
The following status codes are used to indicate specific conditions:
| Status | Description |
|---|---|
| 400 | Input validation errors |
| 401 | Invalid API Key |
| 402 | Feature not enabled - Occurs when a licensed feature has not been enabled for the current license key |
| 403 | Permission denied - Occurs when attempting to access functionality not enabled for a tenant, such as email password sign-up on a tenant with email password disabled |
| 405 | Method not supported |
| 500 | Unhandled exceptions |
App-Level and Tenant-Level APIs
Endpoints can operate at either the Tenant or App level. For detailed information about Apps and Tenants, refer to the Multitenancy documentation.
Some endpoints may operate at either the Tenant or App level based on the provided input parameters.
The WebServerAPI class provides helper functions to access the App or Tenant context passed to the API.
The AppIdentifier (or AppId) is specified by the prefix /appid-<appId> in the request path. When this prefix is absent, the default AppId is public.
Similarly, the TenantIdentifier (or TenantId) is specified by the prefix /<tenantId> in the request path. When this prefix is absent, the default TenantId is public.
Note that while both prefixes are optional, the tenant ID prefix must always follow the app ID prefix.
Certain reserved words are prohibited from being used as tenant IDs, including recipe, hello, and others. The complete list is maintained in the INVALID_WORDS_FOR_TENANTID constant within the io.supertokens.webserver.Utils class.
Both AppId and TenantId are case-insensitive.
Summary of useful functions in the WebserverAPI
getPath()
Abstract method that must be implemented to return the API endpoint path
sendTextResponse()
Sends a text response with specified status code and message
sendJsonResponse()
Sends a JSON response with specified status code and JSON content
doGet(), doPost(), etc.
Default HTTP method handlers that return 405 Method Not Supported, if not overridden
getRID()
Returns the recipe ID for the API handler. Refer Recipe
getVersionFromRequest()
Gets the CDI version from request headers, defaulting to latest supported version
getTenantIdentifier()
Gets the tenant identifier from the request, verifying tenant exists
getAppIdentifier()
Gets the app identifier from the request, verifying app exists
getTenantStorage()
Gets the storage instance for the tenant specified in request
enforcePublicTenantAndGetAllStoragesForApp()
Gets all storage instances for an app, enforcing public tenant access
enforcePublicTenantAndGetPublicTenantStorage()
Gets the public tenant storage for an app
getStorageAndUserIdMappingForTenantSpecificApi()
Gets storage and user ID mapping for tenant-specific APIs
enforcePublicTenantAndGetStorageAndUserIdMappingForAppSpecificApi()
Gets storage and user ID mapping for app-specific APIs
getRIDFromRequest()
Gets the recipe ID from request headers. Refer Recipe
checkAPIKey()
Controls whether an API endpoint is protected by the API Key. It is enabled by default. To disable, override this function and return false