diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 86835ffe72..efb42328ea 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -282,131 +282,37 @@ "icon": "code", "pages": [ { - "group": "@unkey/api", + "group": "Typescript", "pages": [ - "libraries/ts/sdk/overview", + "libraries/ts/api", { - "group": "Keys", + "group": "@unkey/ratelimit", "pages": [ - "libraries/ts/sdk/keys/create", - "libraries/ts/sdk/keys/verify", - "libraries/ts/sdk/keys/get", - "libraries/ts/sdk/keys/update", - "libraries/ts/sdk/keys/update-remaining", - "libraries/ts/sdk/keys/delete", - "libraries/ts/sdk/keys/add-permission", - "libraries/ts/sdk/keys/remove-permission", - "libraries/ts/sdk/keys/set-permission", - "libraries/ts/sdk/keys/add-roles", - "libraries/ts/sdk/keys/remove-roles", - "libraries/ts/sdk/keys/set-roles" - ] - }, - { - "group": "Analytics", - "pages": ["libraries/ts/sdk/analytics/get"] - }, - { - "group": "APIs", - "pages": [ - "libraries/ts/sdk/apis/create", - "libraries/ts/sdk/apis/get", - "libraries/ts/sdk/apis/list-keys", - "libraries/ts/sdk/apis/delete" - ] - }, - { - "group": "Identities", - "pages": [ - "libraries/ts/sdk/identities/create-identity", - "libraries/ts/sdk/identities/get-identity", - "libraries/ts/sdk/identities/update-identity", - "libraries/ts/sdk/identities/list-identity", - "libraries/ts/sdk/identities/delete-identity" - ] - }, - { - "group": "Ratelimits", - "pages": [ - "libraries/ts/sdk/ratelimits/limit", + "libraries/ts/ratelimit/ratelimit", { "group": "Overrides", "pages": [ - "libraries/ts/sdk/ratelimits/overrides/set-override", - "libraries/ts/sdk/ratelimits/overrides/get-override", - "libraries/ts/sdk/ratelimits/overrides/list-overrides", - "libraries/ts/sdk/ratelimits/overrides/delete-override" + "libraries/ts/ratelimit/override/overview", + "libraries/ts/ratelimit/override/set-override", + "libraries/ts/ratelimit/override/get-override", + "libraries/ts/ratelimit/override/list-overrides", + "libraries/ts/ratelimit/override/delete-override" ] } ] }, - { - "group": "Migrations", - "pages": ["libraries/ts/sdk/migrations/migrate-to-unkey"] - }, - { - "group": "Permissions", - "pages": [ - { - "group": "Roles", - "pages": [ - "libraries/ts/sdk/permissions/create-role", - "libraries/ts/sdk/permissions/get-role", - "libraries/ts/sdk/permissions/delete-role" - ] - }, - { - "group": "Permissions", - "pages": [ - "libraries/ts/sdk/permissions/create-permission", - "libraries/ts/sdk/permissions/get-permission", - "libraries/ts/sdk/permissions/delete-permission" - ] - } - ] - } + "libraries/ts/nextjs", + "libraries/ts/hono", + "libraries/ts/cache/overview" ] }, { - "group": "@unkey/ratelimit", - "pages": [ - "libraries/ts/ratelimit/ratelimit", - { - "group": "Overrides", - "pages": [ - "libraries/ts/ratelimit/override/overview", - "libraries/ts/ratelimit/override/set-override", - "libraries/ts/ratelimit/override/get-override", - "libraries/ts/ratelimit/override/list-overrides", - "libraries/ts/ratelimit/override/delete-override" - ] - } - ] + "group": "Go", + "pages": ["libraries/go/api"] }, - "libraries/ts/nextjs", - "libraries/ts/hono", - "libraries/ts/cache/overview", { - "group": "unkey-go", - "pages": ["libraries/go/overview"] - }, - { - "group": "unkey.py", - "pages": [ - "libraries/py/overview", - "libraries/py/async", - { - "group": "Services", - "pages": [ - "libraries/py/services/keys", - "libraries/py/services/apis", - "libraries/py/services/permissions", - "libraries/py/services/migrations", - "libraries/py/services/identities", - "libraries/py/services/ratelimits" - ] - } - ] + "group": "Python", + "pages": ["libraries/py/api"] } ] }, diff --git a/apps/docs/libraries/go/api.mdx b/apps/docs/libraries/go/api.mdx new file mode 100644 index 0000000000..91311baeba --- /dev/null +++ b/apps/docs/libraries/go/api.mdx @@ -0,0 +1,59 @@ +--- +title: "unkey-go" +description: "Unkey's API provides programmatic access for all resources within our platform." +--- + +## SDK Installation + +To add the SDK as a dependency to your project: + +```bash +go get github.com/unkeyed/sdks/api/go/v2 +``` + +## SDK Example Usage + +### Example + +```go +package main + +import ( + "context" + unkey "github.com/unkeyed/sdks/api/go/v2" + "github.com/unkeyed/sdks/api/go/v2/models/components" + "log" + "os" +) + +func main() { + ctx := context.Background() + + s := unkey.New( + unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")), + ) + + res, err := s.Apis.CreateAPI(ctx, components.V2ApisCreateAPIRequestBody{ + Name: "payment-service-production", + }) + if err != nil { + log.Fatal(err) + } + if res.V2ApisCreateAPIResponseBody != nil { + // handle response + } +} + +``` + +## Repository + +{" "} + + The full autogenerated documentation can be found on GitHub. + diff --git a/apps/docs/libraries/go/overview.mdx b/apps/docs/libraries/go/overview.mdx deleted file mode 100644 index a26fb63639..0000000000 --- a/apps/docs/libraries/go/overview.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "Overview" -description: "Go SDK for Unkey" ---- - - - -## SDK Installation - -```bash -go get github.com/unkeyed/unkey/sdks/golang -``` - - -## Example - -```go -package main - -import ( - "context" - unkey "github.com/unkeyed/unkey/sdks/golang" - "github.com/unkeyed/unkey/sdks/golang/models/components" - "github.com/unkeyed/unkey/sdks/golang/models/operations" - "log" -) - -func main() { - s := unkey.New( - unkey.WithSecurity(""), - ) - - request := operations.CreateAPIRequestBody{ - Name: "my-api", - } - - ctx := context.Background() - res, err := s.CreateAPI(ctx, request) - if err != nil { - log.Fatal(err) - } - if res != nil { - // handle response - } -} - -``` - -## Error Handling - -Handling errors in this SDK should largely match your expectations. All operations return a response object or an error, they will never return both. When specified by the OpenAPI spec document, the SDK will return the appropriate subclass. - -| Error Object | Status Code | Content Type | -| -------------------------------- | -------------------------------- | -------------------------------- | -| sdkerrors.ErrBadRequest | 400 | application/json | -| sdkerrors.ErrUnauthorized | 401 | application/json | -| sdkerrors.ErrForbidden | 403 | application/json | -| sdkerrors.ErrNotFound | 404 | application/json | -| sdkerrors.ErrConflict | 409 | application/json | -| sdkerrors.ErrTooManyRequests | 429 | application/json | -| sdkerrors.ErrInternalServerError | 500 | application/json | -| sdkerrors.SDKError | 4xx-5xx | */* | - -### Example - -```go -package main - -import ( - "context" - "errors" - unkey "github.com/unkeyed/unkey/sdks/golang" - "github.com/unkeyed/unkey/sdks/golang/models/components" - "github.com/unkeyed/unkey/sdks/golang/models/operations" - "github.com/unkeyed/unkey/sdks/golang/models/sdkerrors" - "log" -) - -func main() { - s := unkey.New( - unkey.WithSecurity(""), - ) - - request := operations.CreateAPIRequestBody{ - Name: "my-api", - } - - ctx := context.Background() - res, err := s.CreateAPI(ctx, request) - if err != nil { - - var e *sdkerrors.ErrBadRequest - if errors.As(err, &e) { - // handle error - log.Fatal(e.Error()) - } - - var e *sdkerrors.ErrUnauthorized - if errors.As(err, &e) { - // handle error - log.Fatal(e.Error()) - } - - var e *sdkerrors.ErrForbidden - if errors.As(err, &e) { - // handle error - log.Fatal(e.Error()) - } - - var e *sdkerrors.ErrNotFound - if errors.As(err, &e) { - // handle error - log.Fatal(e.Error()) - } - - var e *sdkerrors.ErrConflict - if errors.As(err, &e) { - // handle error - log.Fatal(e.Error()) - } - - var e *sdkerrors.ErrTooManyRequests - if errors.As(err, &e) { - // handle error - log.Fatal(e.Error()) - } - - var e *sdkerrors.ErrInternalServerError - if errors.As(err, &e) { - // handle error - log.Fatal(e.Error()) - } - - var e *sdkerrors.SDKError - if errors.As(err, &e) { - // handle error - log.Fatal(e.Error()) - } - } -} - -``` diff --git a/apps/docs/libraries/py/api.mdx b/apps/docs/libraries/py/api.mdx new file mode 100644 index 0000000000..fb9d3b47cf --- /dev/null +++ b/apps/docs/libraries/py/api.mdx @@ -0,0 +1,111 @@ +--- +title: "unkey.py" +description: "Unkey's API provides programmatic access for all resources within our platform." +--- + +## SDK Installation + +> [!NOTE] > **Python version upgrade policy** +> +> Once a Python version reaches its [official end of life date](https://devguide.python.org/versions/), a 3-month grace period is provided for users to upgrade. Following this grace period, the minimum python version supported in the SDK will be updated. + +The SDK can be installed with either _pip_ or _poetry_ package managers. + +### PIP + +_PIP_ is the default package installer for Python, enabling easy installation and management of packages from PyPI via the command line. + +```bash +pip install unkey.py +``` + +### Poetry + +_Poetry_ is a modern tool that simplifies dependency management and package publishing by using a single `pyproject.toml` file to handle project metadata and dependencies. + +```bash +poetry add unkey.py +``` + +### Shell and script usage with `uv` + +You can use this SDK in a Python shell with [uv](https://docs.astral.sh/uv/) and the `uvx` command that comes with it like so: + +```shell +uvx --from unkey.py python +``` + +It's also possible to write a standalone Python script without needing to set up a whole project like so: + +```python +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.9" +# dependencies = [ +# "unkey.py", +# ] +# /// + +from unkey.py import Unkey + +sdk = Unkey( + # SDK arguments +) + +# Rest of script here... +``` + +Once that is saved to a file, you can run it with `uv run script.py` where +`script.py` can be replaced with the actual file name. + +## SDK Example Usage + +### Example + +```python +# Synchronous Example +from unkey.py import Unkey + + +with Unkey( + root_key="", +) as unkey: + + res = unkey.apis.create_api(name="payment-service-production") + + # Handle response + print(res) +``` + +The same SDK client can also be used to make asynchronous requests by importing asyncio. + +```python +# Asynchronous Example +import asyncio +from unkey.py import Unkey + +async def main(): + + async with Unkey( + root_key="", + ) as unkey: + + res = await unkey.apis.create_api_async(name="payment-service-production") + + # Handle response + print(res) + +asyncio.run(main()) +``` + +## Repository + +{" "} + + The full autogenerated documentation can be found on GitHub. + diff --git a/apps/docs/libraries/py/async.mdx b/apps/docs/libraries/py/async.mdx deleted file mode 100644 index 9d4d8cce1e..0000000000 --- a/apps/docs/libraries/py/async.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Async -description: Using unkey.py synchronous or asynchronous ---- - - -```python -# Synchronous Example -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.liveness.check() - -if res.object is not None: - # handle response - pass -``` - - -The same SDK client can also be used to make asychronous requests by importing asyncio. -```python -# Asynchronous Example -import asyncio -import os -from unkey_py import Unkey - -async def main(): - s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), - ) - res = await s.liveness.check_async() - if res.object is not None: - # handle response - pass - -asyncio.run(main()) -``` diff --git a/apps/docs/libraries/py/overview.mdx b/apps/docs/libraries/py/overview.mdx deleted file mode 100644 index afcc0bafdc..0000000000 --- a/apps/docs/libraries/py/overview.mdx +++ /dev/null @@ -1,463 +0,0 @@ ---- -title: "Overview" -description: "Developer-friendly & type-safe Python SDK for Unkey's API." ---- - - - - - - - -## SDK Installation - -The SDK can be installed with either *pip* or *poetry* package managers. - -### PIP - -*PIP* is the default package installer for Python, enabling easy installation and management of packages from PyPI via the command line. - -```bash -pip install unkey.py -``` - -### Poetry - -*Poetry* is a modern tool that simplifies dependency management and package publishing by using a single `pyproject.toml` file to handle project metadata and dependencies. - -```bash -poetry add unkey.py -``` - -## IDE Support - -### PyCharm - -Generally, the SDK will work well with most IDEs out of the box. However, when using PyCharm, you can enjoy much better integration with Pydantic by installing an additional plugin. - -- [PyCharm Pydantic Plugin](https://docs.pydantic.dev/latest/integrations/pycharm/) - -## SDK Example Usage - -### Example - -```python -# Synchronous Example -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.liveness.check() - -if res.object is not None: - # handle response - pass -``` - - -The same SDK client can also be used to make asychronous requests by importing asyncio. -```python -# Asynchronous Example -import asyncio -import os -from unkey_py import Unkey - -async def main(): - s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), - ) - res = await s.liveness.check_async() - if res.object is not None: - # handle response - pass - -asyncio.run(main()) -``` -## Available Resources and Operations - -
-Available methods - -### [apis](/libraries/py/services/apis) - -* [get](/libraries/py/services/apis#get) -* [create](/libraries/py/services/apis#create) -* [list_keys](/libraries/py/services/apis#list_keys) -* [delete](/libraries/py/services/apis#delete) -* [delete_keys](/libraries/py/services/apis#delete_keys) - -### [identities](/libraries/py/services/identities) - -* [create](/libraries/py/services/identities#create) -* [get](/libraries/py/services/identities#get) -* [list](/libraries/py/services/identities#list) -* [update](/libraries/py/services/identities#update) -* [delete](/libraries/py/services/identities#delete) - -### [keys](/libraries/py/services/keys) - -* [get](/libraries/py/services/keys#get) -* [whoami](/libraries/py/services/keys#whoami) -* [delete](/libraries/py/services/keys#delete) -* [create](/libraries/py/services/keys#create) -* [verify](/libraries/py/services/keys#verify) -* [update](/libraries/py/services/keys#update) -* [update_remaining](/libraries/py/services/keys#update_remaining) -* [get_verifications](/libraries/py/services/keys#get_verifications) -* [add_permissions](/libraries/py/services/keys#add_permissions) -* [remove_permissions](/libraries/py/services/keys#remove_permissions) -* [set_permissions](/libraries/py/services/keys#set_permissions) -* [add_roles](/libraries/py/services/keys#add_roles) -* [remove_roles](/libraries/py/services/keys#remove_roles) -* [set_roles](/libraries/py/services/keys#set_roles) - - -### [migrations](/libraries/py/services/migrations) - -* [create_keys](/libraries/py/services/migrations#create_keys) -* [enqueue](/libraries/py/services/migrations#enqueue) - -### [permissions](/libraries/py/services/permissions) - -* [create](/libraries/py/services/permissions#create) -* [delete](/libraries/py/services/permissions#delete) -* [get](/libraries/py/services/permissions#get) -* [list](/libraries/py/services/permissions#list) -* [create_role](/libraries/py/services/permissions#create_role) -* [delete_role](/libraries/py/services/permissions#delete_role) -* [get_role](/libraries/py/services/permissions#get_role) -* [list_roles](/libraries/py/services/permissions#list_roles) - -### [ratelimits](/libraries/py/services/ratelimits) - -* [limit](/libraries/py/services/ratelimits#limit) - - -
-## Pagination - -Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the -returned response object will have a `Next` method that can be called to pull down the next group of results. If the -return value of `Next` is `None`, then there are no more pages to be fetched. - -Here's an example of one such pagination call: -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.identities.list(limit=100) - -if res.object is not None: - while True: - # handle items - - res = res.next() - if res is None: - break - -``` - -## Retries - -Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK. - -To change the default retry strategy for a single API call, simply provide a `RetryConfig` object to the call: -```python -import os -from unkey.utils import BackoffStrategy, RetryConfig -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.liveness.check(, - RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False)) - -if res.object is not None: - # handle response - pass - -``` - -If you'd like to override the default retry strategy for all operations that support retries, you can use the `retry_config` optional parameter when initializing the SDK: -```python -import os -from unkey.utils import BackoffStrategy, RetryConfig -from unkey_py import Unkey - -s = Unkey( - retry_config=RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False), - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.liveness.check() - -if res.object is not None: - # handle response - pass - -``` -## Error Handling - -Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an exception. - -By default, an API error will raise a models.SDKError exception, which has the following properties: - -| Property | Type | Description | -|-----------------|------------------|-----------------------| -| `.status_code` | *int* | The HTTP status code | -| `.message` | *str* | The error message | -| `.raw_response` | *httpx.Response* | The raw HTTP response | -| `.body` | *str* | The response content | - -When custom error responses are specified for an operation, the SDK may also raise their associated exceptions. You can refer to respective *Errors* tables in SDK docs for more details on possible exception types for each operation. For example, the `check_async` method may raise the following exceptions: - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -### Example - -```python -import os -from unkey_py import Unkey, models - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = None -try: - res = s.liveness.check() - - if res.object is not None: - # handle response - pass - -except models.ErrBadRequest as e: - # handle e.data: models.ErrBadRequestData - raise(e) -except models.ErrUnauthorized as e: - # handle e.data: models.ErrUnauthorizedData - raise(e) -except models.ErrForbidden as e: - # handle e.data: models.ErrForbiddenData - raise(e) -except models.ErrNotFound as e: - # handle e.data: models.ErrNotFoundData - raise(e) -except models.ErrConflict as e: - # handle e.data: models.ErrConflictData - raise(e) -except models.ErrTooManyRequests as e: - # handle e.data: models.ErrTooManyRequestsData - raise(e) -except models.ErrInternalServerError as e: - # handle e.data: models.ErrInternalServerErrorData - raise(e) -except models.SDKError as e: - # handle exception - raise(e) -``` - -## Server Selection - -### Select Server by Index - -You can override the default server globally by passing a server index to the `server_idx: int` optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers: - -| # | Server | Variables | -| - | ------ | --------- | -| 0 | `https://api.unkey.dev` | None | - -#### Example - -```python -import os -from unkey_py import Unkey - -s = Unkey( - server_idx=0, - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.liveness.check() - -if res.object is not None: - # handle response - pass - -``` - - -### Override Server URL Per-Client - -The default server can also be overridden globally by passing a URL to the `server_url: str` optional parameter when initializing the SDK client instance. For example: -```python -import os -from unkey_py import Unkey - -s = Unkey( - server_url="https://api.unkey.dev", - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.liveness.check() - -if res.object is not None: - # handle response - pass - -``` - -## Custom HTTP Client - -The Python SDK makes API calls using the [httpx](https://www.python-httpx.org/) HTTP library. In order to provide a convenient way to configure timeouts, cookies, proxies, custom headers, and other low-level configuration, you can initialize the SDK client with your own HTTP client instance. -Depending on whether you are using the sync or async version of the SDK, you can pass an instance of `HttpClient` or `AsyncHttpClient` respectively, which are Protocol's ensuring that the client has the necessary methods to make API calls. -This allows you to wrap the client with your own custom logic, such as adding custom headers, logging, or error handling, or you can just pass an instance of `httpx.Client` or `httpx.AsyncClient` directly. - -For example, you could specify a header for every request that this sdk makes as follows: -```python -from unkey_py import Unkey -import httpx - -http_client = httpx.Client(headers={"x-custom-header": "someValue"}) -s = Unkey(client=http_client) -``` - -or you could wrap the client with your own custom logic: -```python -from unkey_py import Unkey -from unkey_py.httpclient import AsyncHttpClient -import httpx - -class CustomClient(AsyncHttpClient): - client: AsyncHttpClient - - def __init__(self, client: AsyncHttpClient): - self.client = client - - async def send( - self, - request: httpx.Request, - *, - stream: bool = False, - auth: Union[ - httpx._types.AuthTypes, httpx._client.UseClientDefault, None - ] = httpx.USE_CLIENT_DEFAULT, - follow_redirects: Union[ - bool, httpx._client.UseClientDefault - ] = httpx.USE_CLIENT_DEFAULT, - ) -> httpx.Response: - request.headers["Client-Level-Header"] = "added by client" - - return await self.client.send( - request, stream=stream, auth=auth, follow_redirects=follow_redirects - ) - - def build_request( - self, - method: str, - url: httpx._types.URLTypes, - *, - content: Optional[httpx._types.RequestContent] = None, - data: Optional[httpx._types.RequestData] = None, - files: Optional[httpx._types.RequestFiles] = None, - json: Optional[Any] = None, - params: Optional[httpx._types.QueryParamTypes] = None, - headers: Optional[httpx._types.HeaderTypes] = None, - cookies: Optional[httpx._types.CookieTypes] = None, - timeout: Union[ - httpx._types.TimeoutTypes, httpx._client.UseClientDefault - ] = httpx.USE_CLIENT_DEFAULT, - extensions: Optional[httpx._types.RequestExtensions] = None, - ) -> httpx.Request: - return self.client.build_request( - method, - url, - content=content, - data=data, - files=files, - json=json, - params=params, - headers=headers, - cookies=cookies, - timeout=timeout, - extensions=extensions, - ) - -s = Unkey(async_client=CustomClient(httpx.AsyncClient())) -``` - -## Authentication - -### Per-Client Security Schemes - -This SDK supports the following security scheme globally: - -| Name | Type | Scheme | Environment Variable | -| -------------------- | -------------------- | -------------------- | -------------------- | -| `bearer_auth` | http | HTTP Bearer | `UNKEY_BEARER_AUTH` | - -To authenticate with the API the `bearer_auth` parameter must be set when initializing the SDK client instance. For example: -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.liveness.check() - -if res.object is not None: - # handle response - pass - -``` - -## Debugging - -You can setup your SDK to emit debug logs for SDK requests and responses. - -You can pass your own logger class directly into your SDK. -```python -from unkey_py import Unkey -import logging - -logging.basicConfig(level=logging.DEBUG) -s = Unkey(debug_logger=logging.getLogger("unkey_py")) -``` - -You can also enable a default debug logger by setting an environment variable `UNKEY_DEBUG` to true. - - -# Development - -## Maturity - -This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage -to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally -looking for the latest version. - -## Contributions - -While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. -We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release. - -### SDK Created by [Speakeasy](https://www.speakeasy.com/?utm_source=unkey&utm_campaign=python) diff --git a/apps/docs/libraries/py/services/apis.mdx b/apps/docs/libraries/py/services/apis.mdx deleted file mode 100644 index 54d0b09ec5..0000000000 --- a/apps/docs/libraries/py/services/apis.mdx +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: Apis ---- - -## get - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.apis.get(api_id="api_1234") - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | Example | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `api_id` | *str* | :heavy_check_mark: | N/A | api_1234 | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | - -### Response - -**[models.GetAPIResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/getapiresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## create - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.apis.create(request={ - "name": "my-api", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.CreateAPIRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createapirequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.CreateAPIResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createapiresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## list_keys - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.apis.list_keys(request={ - "api_id": "api_1234", - "limit": 100, -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.ListKeysRequest](https://github.com/unkeyed/unkey-py/tree/main/docs/models/listkeysrequest.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - - - -### Response - -**[models.ListKeysResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/listkeysresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## delete - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.apis.delete(request={ - "api_id": "api_1234", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.DeleteAPIRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deleteapirequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.DeleteAPIResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deleteapiresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrDeleteProtected | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## delete_keys - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.apis.delete_keys(request={ - "api_id": "api_1234", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | -| `request` | [models.DeleteKeysRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deletekeysrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.DeleteKeysResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deletekeysresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | diff --git a/apps/docs/libraries/py/services/identities.mdx b/apps/docs/libraries/py/services/identities.mdx deleted file mode 100644 index 63c9dbe9d8..0000000000 --- a/apps/docs/libraries/py/services/identities.mdx +++ /dev/null @@ -1,266 +0,0 @@ ---- -title: Identities ---- - -## create - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.identities.create(request={ - "external_id": "user_123", - "ratelimits": [ - { - "name": "tokens", - "limit": 10, - "duration": 1000, - }, - { - "name": "tokens", - "limit": 10, - "duration": 1000, - }, - ], -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `request` | [models.CreateIdentityRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createidentityrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.CreateIdentityResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createidentityresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## get - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.identities.get(identity_id="id_1234", external_id="id_1234") - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | Example | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `identity_id` | *Optional[str]* | :heavy_minus_sign: | N/A | id_1234 | -| `external_id` | *Optional[str]* | :heavy_minus_sign: | N/A | id_1234 | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | - -### Response - -**[models.GetIdentityResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/getidentityresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## list - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.identities.list(limit=100) - -if res.object is not None: - while True: - # handle items - - res = res.next() - if res is None: - break - -``` - -### Parameters - -| Parameter | Type | Required | Description | Example | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `environment` | *Optional[str]* | :heavy_minus_sign: | N/A | | -| `limit` | *Optional[int]* | :heavy_minus_sign: | N/A | 100 | -| `cursor` | *Optional[str]* | :heavy_minus_sign: | N/A | | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | - -### Response - -**[models.ListIdentitiesResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/listidentitiesresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## update - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.identities.update(request={ - "identity_id": "id_1234", - "external_id": "user_1234", - "ratelimits": [ - { - "name": "tokens", - "limit": 10, - "duration": 1000, - }, - { - "name": "tokens", - "limit": 10, - "duration": 1000, - }, - { - "name": "tokens", - "limit": 10, - "duration": 1000, - }, - ], -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `request` | [models.UpdateIdentityRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/updateidentityrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.UpdateIdentityResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/updateidentityresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## delete - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.identities.delete(request={ - "identity_id": "id_1234", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `request` | [models.DeleteIdentityRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deleteidentityrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.DeleteIdentityResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deleteidentityresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | diff --git a/apps/docs/libraries/py/services/keys.mdx b/apps/docs/libraries/py/services/keys.mdx deleted file mode 100644 index aac3d1c363..0000000000 --- a/apps/docs/libraries/py/services/keys.mdx +++ /dev/null @@ -1,795 +0,0 @@ ---- -title: Keys ---- -## get - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.get(key_id="key_1234") - -if res.key is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | Example | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `key_id` | *str* | :heavy_check_mark: | N/A | key_1234 | -| `decrypt` | *OptionalNullable[bool]* | :heavy_minus_sign: | N/A | | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | - -### Response - -**[models.GetKeyResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/getkeyresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## whoami - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.whoami(request={ - "key": "sk_123", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.WhoamiRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/whoamirequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.WhoamiResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/whoamiresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## delete - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.delete(request={ - "key_id": "key_1234", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.DeleteKeyRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deletekeyrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.DeleteKeyResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deletekeyresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## create - -### Example Usage - -```python -import os -import unkey -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.create(request={ - "api_id": "api_123", - "name": "my key", - "external_id": "team_123", - "meta": { - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z", - }, - "roles": [ - "admin", - "finance", - ], - "permissions": [ - "domains.create_record", - "say_hello", - ], - "expires": 1623869797161, - "remaining": 1000, - "refill": { - "interval": unkey.CreateKeyInterval.DAILY, - "amount": 100, - }, - "ratelimit": { - "limit": 10, - "type": unkey.CreateKeyType.FAST, - "duration": 60000, - }, - "enabled": False, -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.CreateKeyRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createkeyrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.CreateKeyResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createkeyresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## verify - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.verify(request={ - "key": "sk_1234", - "api_id": "api_1234", - "ratelimits": [ - { - "name": "tokens", - "limit": 500, - "duration": 3600000, - }, - { - "name": "tokens", - "limit": 20000, - "duration": 86400000, - }, - ], -}) - -if res.v1_keys_verify_key_response is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `request` | [models.V1KeysVerifyKeyRequest](https://github.com/unkeyed/unkey-py/tree/main/docs/models/v1keysverifykeyrequest.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.VerifyKeyResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/verifykeyresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## update - -### Example Usage - -```python -import os -import unkey -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.update(request={ - "key_id": "key_123", - "name": "Customer X", - "external_id": "user_123", - "meta": { - "roles": [ - "admin", - "user", - ], - "stripeCustomerId": "cus_1234", - }, - "expires": 0, - "ratelimit": { - "limit": 10, - "type": unkey.UpdateKeyType.FAST, - "refill_rate": 1, - "refill_interval": 60, - }, - "remaining": 1000, - "refill": { - "interval": unkey.UpdateKeyInterval.DAILY, - "amount": 100, - }, - "enabled": True, - "roles": [ - { - "id": "perm_123", - }, - { - "name": "dns.record.create", - }, - { - "name": "dns.record.delete", - "create": True, - }, - ], - "permissions": [ - { - "id": "perm_123", - }, - { - "name": "dns.record.create", - }, - { - "name": "dns.record.delete", - "create": True, - }, - ], -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.UpdateKeyRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/updatekeyrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.UpdateKeyResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/updatekeyresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## update_remaining - -### Example Usage - -```python -import os -import unkey -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.update_remaining(request={ - "key_id": "key_123", - "op": unkey.Op.SET, - "value": 1, -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `request` | [models.UpdateRemainingRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/updateremainingrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.UpdateRemainingResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/updateremainingresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## get_verifications - -### Example Usage - -```python -import os -import unkey -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.get_verifications(request={ - "key_id": "key_1234", - "owner_id": "chronark", - "start": 1620000000000, - "end": 1620000000000, - "granularity": unkey.Granularity.DAY, -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| `request` | [models.GetVerificationsRequest](https://github.com/unkeyed/unkey-py/tree/main/docs/models/getverificationsrequest.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.GetVerificationsResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/getverificationsresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## add_permissions - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.add_permissions(request={ - "key_id": "", - "permissions": [ - {}, - ], -}) - -if res.response_bodies is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `request` | [models.AddPermissionsRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/addpermissionsrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.AddPermissionsResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/addpermissionsresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## remove_permissions - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.remove_permissions(request={ - "key_id": "", - "permissions": [ - { - "id": "perm_123", - }, - { - "name": "dns.record.create", - }, - ], -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| `request` | [models.RemovePermissionsRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/removepermissionsrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.RemovePermissionsResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/removepermissionsresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## set_permissions - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.set_permissions(request={ - "key_id": "", - "permissions": [ - { - "id": "perm_123", - }, - { - "name": "dns.record.create", - }, - { - "name": "dns.record.delete", - "create": True, - }, - ], -}) - -if res.response_bodies is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `request` | [models.SetPermissionsRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/setpermissionsrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.SetPermissionsResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/setpermissionsresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## add_roles - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.add_roles(request={ - "key_id": "", - "roles": [ - { - "id": "role_123", - }, - { - "name": "dns.record.create", - }, - { - "name": "dns.record.delete", - "create": True, - }, - ], -}) - -if res.response_bodies is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.AddRolesRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/addrolesrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.AddRolesResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/addrolesresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## remove_roles - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.remove_roles(request={ - "key_id": "", - "roles": [ - { - "id": "role_123", - }, - { - "name": "dns.record.create", - }, - ], -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `request` | [models.RemoveRolesRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/removerolesrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.RemoveRolesResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/removerolesresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## set_roles - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.keys.set_roles(request={ - "key_id": "", - "roles": [ - { - "id": "role_123", - }, - { - "name": "dns.record.create", - }, - { - "name": "dns.record.delete", - "create": True, - }, - ], -}) - -if res.response_bodies is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.SetRolesRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/setrolesrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.SetRolesResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/setrolesresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | diff --git a/apps/docs/libraries/py/services/migrations.mdx b/apps/docs/libraries/py/services/migrations.mdx deleted file mode 100644 index b70767f594..0000000000 --- a/apps/docs/libraries/py/services/migrations.mdx +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Migrations ---- - -## create_keys - -### Example Usage - -```python -import os -import unkey -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.migrations.create_keys(request=[ - { - "api_id": "api_123", - "name": "my key", - "start": "unkey_32kq", - "owner_id": "team_123", - "meta": { - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z", - }, - "roles": [ - "admin", - "finance", - ], - "permissions": [ - "domains.create_record", - "say_hello", - ], - "expires": 1623869797161, - "remaining": 1000, - "refill": { - "interval": unkey.V1MigrationsCreateKeysInterval.DAILY, - "amount": 100, - }, - "ratelimit": { - "limit": 10, - "refill_rate": 1, - "refill_interval": 60, - "type": unkey.V1MigrationsCreateKeysType.FAST, - }, - "enabled": False, - }, -]) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [List[models.RequestBody]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.V1MigrationsCreateKeysResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/v1migrationscreatekeysresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## enqueue - -### Example Usage - -```python -import os -import unkey -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.migrations.enqueue(request={ - "migration_id": "", - "api_id": "", - "keys": [ - { - "name": "my key", - "start": "unkey_32kq", - "owner_id": "team_123", - "meta": { - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z", - }, - "roles": [ - "admin", - "finance", - ], - "permissions": [ - "domains.create_record", - "say_hello", - ], - "expires": 1623869797161, - "remaining": 1000, - "refill": { - "interval": unkey.V1MigrationsEnqueueKeysInterval.DAILY, - "amount": 100, - }, - "ratelimit": { - "limit": 10, - "duration": 60000, - "type": unkey.V1MigrationsEnqueueKeysType.FAST, - }, - "enabled": False, - }, - ], -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| `request` | [models.V1MigrationsEnqueueKeysRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/v1migrationsenqueuekeysrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.V1MigrationsEnqueueKeysResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/v1migrationsenqueuekeysresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | diff --git a/apps/docs/libraries/py/services/permissions.mdx b/apps/docs/libraries/py/services/permissions.mdx deleted file mode 100644 index 0e8e3c7851..0000000000 --- a/apps/docs/libraries/py/services/permissions.mdx +++ /dev/null @@ -1,363 +0,0 @@ ---- -title: Permissions ---- - -## create - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.permissions.create(request={ - "name": "record.write", - "description": "record.write can create new dns records for our domains.", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `request` | [models.CreatePermissionRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createpermissionrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.CreatePermissionResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createpermissionresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## delete - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.permissions.delete(request={ - "permission_id": "perm_123", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `request` | [models.DeletePermissionRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deletepermissionrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.DeletePermissionResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deletepermissionresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## get - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.permissions.get(permission_id="perm_123") - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | Example | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `permission_id` | *str* | :heavy_check_mark: | N/A | perm_123 | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | - -### Response - -**[models.GetPermissionResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/getpermissionresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## list - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.permissions.list() - -if res.response_bodies is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.ListPermissionsResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/listpermissionsresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## create_role - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.permissions.create_role(request={ - "name": "dns.records.manager", - "description": "dns.records.manager can read and write dns records for our domains.", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | -| `request` | [models.CreateRoleRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createrolerequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.CreateRoleResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/createroleresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## delete_role - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.permissions.delete_role(request={ - "role_id": "role_123", -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------- | -| `request` | [models.DeleteRoleRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deleterolerequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.DeleteRoleResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/deleteroleresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## get_role - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.permissions.get_role(role_id="role_123") - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | Example | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `role_id` | *str* | :heavy_check_mark: | N/A | role_123 | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | | - -### Response - -**[models.GetRoleResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/getroleresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | - -## list_roles - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.permissions.list_roles() - -if res.response_bodies is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.ListRolesResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/listrolesresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | diff --git a/apps/docs/libraries/py/services/ratelimits.mdx b/apps/docs/libraries/py/services/ratelimits.mdx deleted file mode 100644 index 690a338e7d..0000000000 --- a/apps/docs/libraries/py/services/ratelimits.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Ratelimits ---- - -## limit - -### Example Usage - -```python -import os -from unkey_py import Unkey - -s = Unkey( - bearer_auth=os.getenv("UNKEY_BEARER_AUTH", ""), -) - -res = s.ratelimits.limit(request={ - "identifier": "user_123", - "limit": 10, - "duration": 60000, - "namespace": "email.outbound", - "cost": 2, - "resources": [ - { - "type": "organization", - "id": "org_123", - "name": "unkey", - }, - ], -}) - -if res.object is not None: - # handle response - pass - -``` - -### Parameters - -| Parameter | Type | Required | Description | -| ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | -| `request` | [models.LimitRequestBody](https://github.com/unkeyed/unkey-py/tree/main/docs/models/limitrequestbody.md) | :heavy_check_mark: | The request object to use for the request. | -| `retries` | [Optional[utils.RetryConfig]](https://github.com/unkeyed/unkey-py/tree/main/docs/models/utils/retryconfig.md) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | - -### Response - -**[models.LimitResponse](https://github.com/unkeyed/unkey-py/tree/main/docs/models/limitresponse.md)** - -### Errors - -| Error Type | Status Code | Content Type | -| ----------------------------- | ----------------------------- | ----------------------------- | -| models.ErrBadRequest | 400 | application/json | -| models.ErrUnauthorized | 401 | application/json | -| models.ErrForbidden | 403 | application/json | -| models.ErrNotFound | 404 | application/json | -| models.ErrConflict | 409 | application/json | -| models.ErrTooManyRequests | 429 | application/json | -| models.ErrInternalServerError | 500 | application/json | -| models.SDKError | 4XX, 5XX | \*/\* | diff --git a/apps/docs/libraries/ts/api.mdx b/apps/docs/libraries/ts/api.mdx new file mode 100644 index 0000000000..8d8e4a96fc --- /dev/null +++ b/apps/docs/libraries/ts/api.mdx @@ -0,0 +1,74 @@ +--- +title: "@unkey/api" +description: "Unkey's API provides programmatic access for all resources within our platform." +--- + +## SDK Installation + +The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [bun](https://bun.sh/) or [yarn](https://classic.yarnpkg.com/en/) package managers. + + + +```bash npm +npm add @unkey/api +``` + +```bash pnpm +pnpm add @unkey/api +``` + +```bash bun +bun add @unkey/api +``` + +```bash yarn +yarn add @unkey/api zod + +# Note that Yarn does not install peer dependencies automatically. You will need +# to install zod as shown above. +``` + + + + + {" "} + This package is published with CommonJS and ES Modules (ESM) support. + + +## Requirements + +For supported JavaScript runtimes, please consult [RUNTIMES.md](https://github.com/unkeyed/sdks/blob/main/api/ts/RUNTIMES.md). + +## SDK Example Usage + +### Example + +```typescript +import { Unkey } from "@unkey/api"; + +const unkey = new Unkey({ + rootKey: process.env["UNKEY_ROOT_KEY"], +}); + +async function run() { + const result = await unkey.apis.createApi({ + name: "payment-service-production", + }); + + console.log(result); +} + +run(); +``` + +## Repository + +{" "} + + The full autogenerated documentation can be found on GitHub. + diff --git a/apps/docs/libraries/ts/hono.mdx b/apps/docs/libraries/ts/hono.mdx index dfaaae8ea8..c6430bfddc 100644 --- a/apps/docs/libraries/ts/hono.mdx +++ b/apps/docs/libraries/ts/hono.mdx @@ -17,24 +17,25 @@ description: "Hono.js middleware for authenticating API keys" - ```bash npm - npm install @unkey/hono - ``` +```bash npm + npm install @unkey/hono +``` + +```bash pnpm + pnpm add @unkey/hono +``` - ```bash pnpm - pnpm add @unkey/hono - ``` +```bash yarn + yarn add @unkey/hono +``` - ```bash yarn - yarn add @unkey/hono - ``` +```bash bun + bun install @unkey/hono +``` - ```bash bun - bun install @unkey/hono - ``` -Let's dive straight in. The minimal setup looks like this. All you need is your api id. Go to [/app/api](https://app.unkey.com/apis), select your API and copy the id. +Let's dive straight in. The minimal setup looks like this. All you need is your root key with permission to verify keys. Go to [/app/api](https://app.unkey.com/settings/root-keys) and create a key with the `verify_key` permission. By default it tries to grab the api key from the `Authorization` header and then verifies it with unkey. The result of the verification will be written to the context and can be access with `c.get("unkey")`. @@ -46,7 +47,7 @@ import { type UnkeyContext, unkey } from "@unkey/hono"; const app = new Hono<{ Variables: { unkey: UnkeyContext } }>(); app.use("*", unkey({ - apiId: "" + rootKey: "" })); @@ -68,6 +69,7 @@ By default the middleware tries to grab the api key from the `Authorization` hea app.use( "*", unkey({ + rootKey: "", getKey: (c) => c.req.header("x-api-key"), }) ); @@ -85,6 +87,7 @@ To customize the response in case the header is missing, just return a response app.use( "*", unkey({ + rootKey: "", getKey: (c) => { const key = c.req.header("x-api-key"); if (!key) { @@ -98,31 +101,11 @@ app.use( ### Handle errors -If omited, the middleware will throw an `HTTPException` like hono [recommends](https://hono.dev/api/exception) - -To handle errors globally you can pass an `onError` handler to the middleware. -The handler will be called with the context and the error. - - - - The machine readable error code - - - A link to the docs to read more about this error type. - - - A human readable message to help debugging the error. - - - A trace id useful to debug it on Unkey's side, please provide this to - support if you need help. - - - ```ts app.use( "*", unkey({ + rootKey: process.env.UNKEY_ROOT_KEY!, onError: (c, err) => { // handle error return c.text("unauthorized", 401); @@ -143,6 +126,7 @@ See [here](/libraries/ts/sdk/keys/verify#response) for the full `result` object. app.use( "*", unkey({ + rootKey: process.env.UNKEY_ROOT_KEY!, handleInvalidKey: (c, result) => { return c.json( { @@ -156,16 +140,6 @@ app.use( ); ``` -### Disable telemetry - -By default, Unkey collects anonymous telemetry data to help us understand how our SDKs are used. - -If you wish to disable this, you can do so by passing a boolean flag to the constructor: - -```ts -app.use("*", unkey({ disableTelemetry: true })); -``` - ### Pass verification tags You can pass tags to the verification request to help you filter keys later. @@ -173,7 +147,7 @@ You can pass tags to the verification request to help you filter keys later. ```ts (c, next) => unkey({ - apiId: env.UNKEY_API_ID, + rootKey: process.env.UNKEY_ROOT_KEY!, tags: [`path=${c.req.path}`], })(c, next); ``` diff --git a/apps/docs/libraries/ts/nextjs.mdx b/apps/docs/libraries/ts/nextjs.mdx index 22f26a9b31..857b0205ff 100644 --- a/apps/docs/libraries/ts/nextjs.mdx +++ b/apps/docs/libraries/ts/nextjs.mdx @@ -5,48 +5,52 @@ description: "Next.js SDK for Unkey" The official Next.js SDK for Unkey. Use this within your [route handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) as a simple, type-safe way to verify API keys. - - - + ## Install - ```bash npm - npm install @unkey/nextjs - ``` +```bash npm + npm install @unkey/nextjs +``` - ```bash pnpm - pnpm add @unkey/nextjs - ``` +```bash pnpm + pnpm add @unkey/nextjs +``` - ```bash yarn - yarn add @unkey/nextjs - ``` +```bash yarn + yarn add @unkey/nextjs +``` + +```bash bun + bun add @unkey/nextjs +``` - ```bash bun - bun install @unkey/nextjs - ``` Protecting API routes is as simple as wrapping them with the `withUnkey` handler: ```ts -import { NextRequestWithUnkeyContext, withUnkey } from '@unkey/nextjs'; - -export const POST = withUnkey(async (req) => { - - // Process the request here - // You have access to the verification response using `req.unkey` - console.log(req.unkey); - - return new Response('Your API key is valid!'); -},{ apiId: process.env.UNKEY_API_ID! }); +import { NextRequestWithUnkeyContext, withUnkey } from "@unkey/nextjs"; + +export const POST = withUnkey( + async (req: NextRequestWithUnkeyContext) => { + // Process the request here + // You have access to the verification response using `req.unkey` + console.log(req.unkey); + + return new Response("Your API key is valid!"); + }, + { rootKey: process.env.UNKEY_ROOT_KEY! } +); +); ``` -That's it! Since this is just handling key verification, there's no need to specify a root key as an environment variable. - If you want to customize how `withUnkey` processes incoming requests, you can do so as follows: ### `getKey` @@ -55,11 +59,14 @@ By default, withUnkey will look for a bearer token located in the `authorization in the configuration object: ```ts -export const GET = withUnkey(async (req) => { - // ... -}, { - getKey: (req) => new URL(req.url).searchParams.get("key"), -}); +export const GET = withUnkey( + async (req) => { + // ... + }, + { + rootKey: process.env.UNKEY_ROOT_KEY!, + getKey: (req) => new URL(req.url).searchParams.get("key"), + } ``` ### `onError` @@ -67,14 +74,18 @@ export const GET = withUnkey(async (req) => { You can specify custom error handling. By default errors will be logged to the console, and `withUnkey` will return a NextResponse with status 500. ```ts -export const GET = withUnkey(async (req) => { - // ... -}, { - onError: async (req, res) => { - await analytics.trackEvent(`Error ${res.code}: ${res.message}`) - return new NextResponse("Unkey error", { status: 500 }) - } -}); +export const GET = withUnkey( + async (req) => { + // ... + }, + { + rootKey: process.env.UNKEY_ROOT_KEY!, + onError: async (req, res) => { + await analytics.trackEvent(`Error ${res.code}: ${res.message}`); + return new NextResponse("Unkey error", { status: 500 }); + }, + } +); ``` ### `handleInvalidKey` @@ -82,24 +93,15 @@ export const GET = withUnkey(async (req) => { Specify what to do if Unkey reports that your key is invalid. ```ts -export const GET = withUnkey(async (req) => { - // ... -}, { - handleInvalidKey: (req, res) => { - return new Response("Unauthorized", { status: 401 }) - } -}); -``` - - -### Disable telemetry - -By default, Unkey collects anonymous telemetry data to help us understand how our SDKs are used. - -If you wish to disable this, you can do so by passing a boolean flag to the constructor: - -```ts -export const GET = withUnkey(async (req) => { - // ... -}, { disableTelemetry: true }); +export const GET = withUnkey( + async (req) => { + // ... + }, + { + rootKey: process.env.UNKEY_ROOT_KEY!, + handleInvalidKey: (req, res) => { + return new Response("Unauthorized", { status: 401 }); + }, + } +); ``` diff --git a/apps/docs/libraries/ts/sdk/analytics/get.mdx b/apps/docs/libraries/ts/sdk/analytics/get.mdx deleted file mode 100644 index 5db2a33743..0000000000 --- a/apps/docs/libraries/ts/sdk/analytics/get.mdx +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: "Get Verifications" -description: "Retrieve usage data from unkey to power your dashboards, reports or usage-based billing." ---- - - - ```ts - const { result, error } = await unkey.analytics.getVerifications({ - apiId: "api_123", - }); - - if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; - } - - console.log(result) - - ``` - - - -```json -{ - "result": [ - { - "time": 123, - "valid": 123, - "notFound": 123, - "forbidden": 123, - "usageExceeded": 123, - "rateLimited": 123, - "unauthorized": 123, - "disabled": 123, - "insufficientPermissions": 123, - "expired": 123, - "total": 123, - "tag": "path/user_123", - "tags": [ - "path/user_123", - "path/create", - "path/delete/" - ], - "keyId": "key_123", - "identity": { - "id": "id_123", - "externalId": "user_123" - } - } - ] -} -``` - - - - -To use this function, your root key must have the `api.*.read_api permission`. - - -## Request - - - Select the API. Only keys belonging to this API will be included. - - - Filtering by externalId allows you to narrow down the search to a specific user or organisation. - - - Only include data for a specific key or keys. - - When you are providing zero or more than one key ids, all usage counts are aggregated and summed up. Send multiple requests with one keyId each if you need counts per key. - - -Only include data for a specific tag or tags. - -When you are providing zero or more than one tag, all usage counts are aggregated and summed up. Send multiple requests with one tag each if you need counts per tag. - - - -The start of the period to fetch usage for as unix milliseconds timestamp. - - - - The end of the period to fetch usage for as unix milliseconds timestamp. - - - - By default, datapoints are not aggregated, however you probably want to get a breakdown per time, key or identity. - - Grouping by tags and by tag is mutually exclusive. - - - - - Limit the number of returned datapoints. - This may become useful for querying the top 10 identities based on usage. - - - - Sort the output by a specific value. You can use this in combination with the order param. - - - - - Define the order of sorting. Use this in combination with orderBy - - -## Response - - - Total number of verifications in the current time slice, regardless of outcome. - - - - Unix timestamp in milliseconds of the start of the current time slice. - - - - Total number of valid verifications in the current time slice - - - - Total number of not found responses in the current time slice - - - Total number of forbidden requests in the current time slice - - - Total number of usage exceeded verifications in the current time slice - - - Total number of rateLimited verifications in the current time slice - - - Total number of unauthorized verifications in the current time slice - - - Total number of disabled verifications in the current time slice - - - Total number of insufficient permissions verifications in the current time slice - - - Total number of expired verifications in the current time slice - - - - Only available when grouping by tag. - - - - Only available when grouping by tag. - - - - Only available when specifying groupBy=key in the query. - In this case there would be one datapoint per time and groupBy target. - - - -Only available when specifying groupBy=identity in the query. -In this case there would be one datapoint per time and groupBy target. - - - The id of the identity - - -The external id of the identity - - - diff --git a/apps/docs/libraries/ts/sdk/apis/create.mdx b/apps/docs/libraries/ts/sdk/apis/create.mdx deleted file mode 100644 index 2b269ca5ac..0000000000 --- a/apps/docs/libraries/ts/sdk/apis/create.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Create" -description: "Create a new API" ---- - - - -```ts -const { result, error } =await unkey.apis.create({ name: "Unkey production" }); -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "result": { - "apiId" : "api_123" - } -} -``` - - - -## Request - - - The name of the API - - -## Response - - - - - - The id of the newly created API - - - - diff --git a/apps/docs/libraries/ts/sdk/apis/delete.mdx b/apps/docs/libraries/ts/sdk/apis/delete.mdx deleted file mode 100644 index 1c981f7fc1..0000000000 --- a/apps/docs/libraries/ts/sdk/apis/delete.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Delete" -description: "Permanently delete an API and revoke all keys associated with it." ---- - - - -```ts -const { result, error } = await unkey.apis.delete({ apiId: "api_123" }); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - -```json -{ - "result": {} -} -``` - - - -## Request - - - The id of the api to be deleted. - - -## Response - - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/apis/get.mdx b/apps/docs/libraries/ts/sdk/apis/get.mdx deleted file mode 100644 index f0f829fc6f..0000000000 --- a/apps/docs/libraries/ts/sdk/apis/get.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "Get" -description: "Retrieve the configuration of an API" ---- - - - -```ts -const { result, error } = await unkey.apis.get({ - apiId: "api_123", -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "result": { - "id": 'api_123', - "name": 'My API', - "workspaceId": 'ws_123' - } -} -``` - - - -## Request - - - The id of the api to retrieve. - - -## Response - - - - - - The id of the api. - - - - The human readable name you gave this api. - - - - The id of the workspace in which this api is. - - - - diff --git a/apps/docs/libraries/ts/sdk/apis/list-keys.mdx b/apps/docs/libraries/ts/sdk/apis/list-keys.mdx deleted file mode 100644 index d65d4db02e..0000000000 --- a/apps/docs/libraries/ts/sdk/apis/list-keys.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: "List Keys" -description: "Get a list of keys belonging to an API" ---- - - - -```ts -const { result, error } = await unkey.apis.listKeys({ - apiId: "api_QUGih1EMtBy9eSSf3vujmF", - limit: 100, -}) - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result) -``` - - - - -```json -{ - "result": { - "keys": [ - { - "id": "key_HPnfviesBEKHnZBFFiY4fg", - "apiId": "api_QUGih1EMtBy9eSSf3vujmF", - "workspaceId": "ws_o17fS1LvwtRswPdncAcUM", - "start": "key_Crg", - "createdAt": 1687642066782, - "expires": null, - "ratelimit": { - "type": "fast", - "limit": 11, - "refillRate": 11, - "refillInterval": 11 - } - }, - ... - ], - "total": 4 - } -} -``` - - - -## Request - - - The ID of the api you want to retrieve. - - - - Limit the number of returned keys, the maximum is 100. - - - -Specify an offset for pagination. - -_Example:_ -An offset of `4` will skip the first 4 keys and return keys starting at the 5th position. - - - - -Filter by `ownerId`. - -If provided, this will only return keys where the `ownerId` matches. - - - -## Response - - - - - - - - - -The unique key id, use this to reference the key directly when fetching or revoking. - - - - - The API id where this key belongs to. - - - - The workspace id where this key belongs to. - - - - The first few characters of the key. This can be useful when displaying it your users, so they can match it. - - - - - - The name you gave this key. - - - - - Your user's Id. This will provide a link between Unkey and your customer record. - -When validating a key, we will return this back to you, so you can clearly identify your user from their api key. - - - - -This is a place for dynamic meta data, anything that feels useful for you should go here - -Example: - -```json -{ - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z" -} -``` - - - - When the key was created, unix timestamp in milliseconds. - - - - If set, this is when the key ceases to exist, unix timestamp in milliseconds. - Once keys expire they will automatically be deleted and are no longer valid. - - - - - How many more times this key can be used. - - - - -The ratelimit of this key, if configured. - - - - - Either `fast` or `consistent`. - -Read more [here](/apis/features/ratelimiting) - - - - The total amount of burstable requests. - - - - How many tokens to refill during each `refillInterval` - - - Determines the speed at which tokens are refilled. - -In milliseconds - - - - - - - - - -{" "} - - How many keys in total there are in this API. Useful to paginate through this - endpoint. - - - - diff --git a/apps/docs/libraries/ts/sdk/identities/create-identity.mdx b/apps/docs/libraries/ts/sdk/identities/create-identity.mdx deleted file mode 100644 index 8c61550de3..0000000000 --- a/apps/docs/libraries/ts/sdk/identities/create-identity.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "Create An Identity" -description: "Create a new identity in the system. This might not be necessary as newly created keys automatically create an identity if required." ---- - - - -```ts -const { result, error } = await unkey.identities.create({ - externalId: "user_123", - ratelimits: [ - { - name: "tokens", - limit: 10, - duration: 1000, - }, - ], -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "result": { - "identityId": "id_123" - } -} -``` - - - -## Request - - - The id of this identity in your system. - - This usually comes from your authentication provider and could be a userId, organisationId or even an email. - - It does not matter what you use, as long as it uniquely identifies something in your application. - - externalIds are unique across your workspace and therefore a CONFLICT error is returned when you try to create duplicates. - - Minimum length: `3` - - Example: `"user_123"` - - - -This is a place for dynamic meta data, anything that feels useful for you should go here - -Example: - -```json -{ - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z" -} -``` - - - Attach ratelimits to this identity. - - When verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits. - - - - The name of this limit. You will need to use this again when verifying a key. - - Example:`"tokens"` - - - - How many requests may pass within a given window before requests are rejected. - - Required range: `x >= 1` - - Example:`10` - - - - - The duration for each ratelimit window in milliseconds. - - Required range: `x >= 1000` - - Example: `1000` - - - -## Response - - - The id of the identity. Used internally, you do not need to store this. - - - Example: `"id_123"` - - diff --git a/apps/docs/libraries/ts/sdk/identities/delete-identity.mdx b/apps/docs/libraries/ts/sdk/identities/delete-identity.mdx deleted file mode 100644 index 5a5eafa393..0000000000 --- a/apps/docs/libraries/ts/sdk/identities/delete-identity.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: "Delete An Identity" -description: "Delete an identity. This will not revoke the keys associated with the identity." ---- - - - -```ts -const { result, error } = await unkey.identities.delete({ - identityId: "id_1234" -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "result": {} -} -``` - - -## Request - - - The ID of the identity you want to delete. - - -## Response - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/identities/get-identity.mdx b/apps/docs/libraries/ts/sdk/identities/get-identity.mdx deleted file mode 100644 index df05c4bcbb..0000000000 --- a/apps/docs/libraries/ts/sdk/identities/get-identity.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: "Get An Identity" -description: "Retrieve an identity from the Unkey system" ---- - - - -```ts -const { result, error } = await unkey.identities.get({ - externalId: "user_123", -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "result": { - "id": "id_123", - "externalId": "user_123", - "meta": {}, - "ratelimits": [ - { - "name": "tokens", - "limit": 10, - "duration": 1000 - } - ] - } -} -``` - - - -## Request - - - The externalId of the identity to fetch, use either identityId or externalId, if both are provided, identityId takes precedence. - - - - The id of the identity to fetch, use either identityId or externalId, if both are provided, identityId takes precedence. - - - -## Response - - - The id of the identity. Used internally, you do not need to store this. - Example: `"id_123"` - - - - - The id in your system - - - - -This is a place for dynamic meta data, anything that feels useful for you should go here - -Example: - -```json -{ - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z" -} -``` - - - Attach ratelimits to this identity. - - When verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits. - - - - The name of this limit. You will need to use this again when verifying a key. - - Example:`"tokens"` - - - - How many requests may pass within a given window before requests are rejected. - - Required range: `x >= 1` - - Example:`10` - - - - - The duration for each ratelimit window in milliseconds. - - Required range: `x >= 1000` - - Example: `1000` - - - diff --git a/apps/docs/libraries/ts/sdk/identities/list-identity.mdx b/apps/docs/libraries/ts/sdk/identities/list-identity.mdx deleted file mode 100644 index fc95b716a6..0000000000 --- a/apps/docs/libraries/ts/sdk/identities/list-identity.mdx +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "List Identities" -description: "List all identities associated with your workspace" ---- - - - -```ts -const { result, error } = await unkey.identities.list({ - limit: 100 -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result); -``` - - - - -```json -{ - "result": { - "identities": [ - { - "id": "", - "externalId": "", - "ratelimits": [ - { - "name": "tokens", - "limit": 10, - "duration": 1000 - } - ] - } - ], - "cursor": "eyJrZXkiOiJrZXlfMTIzNCJ9", - "total": 100 - } -} -``` - - - -## Request - - - This is not yet used but here for future compatibility. - - - - The maximum number of identities to return - - Required range: `1 <= x <= 100` - - Example: `100` - - - - Use this to fetch the next page of results. A new cursor will be returned in the response if there are more results. - - - -## Response - - - A list of identity objects, each containing its `id`, `externalId`, and associated `ratelimits`. - - - - The id of the identity. Used internally, you do not need to store this. - Example: `"id_123"` - - - - - The id in your system - - - - - Attach ratelimits to this identity. - - When verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits. - - - - The name of this limit. You will need to use this again when verifying a key. - - Example:`"tokens"` - - - - How many requests may pass within a given window before requests are rejected. - - Required range: `x >= 1` - - Example:`10` - - - - - The duration for each ratelimit window in milliseconds. - - Required range: `x >= 1000` - - Example: `1000` - - - - - - - - -The total number of identities for this environment - - - - The cursor to use for the next page of results, if no cursor is returned, there are no more results - - Example:`"eyJrZXkiOiJrZXlfMTIzNCJ9"` - diff --git a/apps/docs/libraries/ts/sdk/identities/update-identity.mdx b/apps/docs/libraries/ts/sdk/identities/update-identity.mdx deleted file mode 100644 index 7a3eda9ed6..0000000000 --- a/apps/docs/libraries/ts/sdk/identities/update-identity.mdx +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: "Update An Identity" -description: "Update a current identity in the system." ---- - - - -```ts -const { result, error } = await unkey.identities.update({ - externalId: "user_123", - ratelimits: [ - { - name: "tokens", - limit: 10, - duration: 1000, - }, - ], -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "result": { - "id": "id_1234", - "externalId": "user_1234", - "meta": { - "stripeSubscriptionId": "sub_1234" - }, - "ratelimits": [ - { - "name": "tokens", - "limit": 10, - "duration": 1000 - } - ] - } -} -``` - - - -## Request - - - The `identityId` of the identity to update, use either `identityId` or `externalId`, if both are provided, `identityId` takes precedence. - - Minimum length: `1` - - Example: `"id_1234"` - - - - The `externalId` of the identity to update, use either `identityId` or `externalId`, if both are provided, `identityId` takes precedence. - - Minimum length: 1 - - Example: `"user_1234"` - - - -This is a place for dynamic meta data, anything that feels useful for you should go here - -Example: - -```json -{ - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z" -} -``` - - - Attach ratelimits to this identity. - - When verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits. - - - - The name of this limit. You will need to use this again when verifying a key. - - Example:`"tokens"` - - - - How many requests may pass within a given window before requests are rejected. - - Required range: `x >= 1` - - Example:`10` - - - - - The duration for each ratelimit window in milliseconds. - - Required range: `x >= 1000` - - Example: `1000` - - - - - - This is not yet used but here for future compatibility. - - - -## Response - - - The id of the identity. Used internally, you do not need to store this. - Example: `"id_123"` - - - - - The id in your system - - - - -This is a place for dynamic meta data, anything that feels useful for you should go here - -Example: - -```json -{ - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z" -} -``` - - - Attach ratelimits to this identity. - - When verifying keys, you can specify which limits you want to use and all keys attached to this identity, will share the limits. - - - - The name of this limit. You will need to use this again when verifying a key. - - Example:`"tokens"` - - - - How many requests may pass within a given window before requests are rejected. - - Required range: `x >= 1` - - Example:`10` - - - - - The duration for each ratelimit window in milliseconds. - - Required range: `x >= 1000` - - Example: `1000` - - - diff --git a/apps/docs/libraries/ts/sdk/keys/add-permission.mdx b/apps/docs/libraries/ts/sdk/keys/add-permission.mdx deleted file mode 100644 index 9abc4f0361..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/add-permission.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Add Permissions" -description: "Add one or more permissions to a key." ---- - - - -```ts -const { result, error } = await unkey.keys.addPermissions({ - keyId: "key_123", - permissions: [{ - "name": "email.test", - "create": true - }] -}) - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result) - -``` - - - - -```json -{ - "result": [ - { - "id": 'perm_45TTRKT5Yh28M6Qj', - "name": 'email.test' - } - ] -} -``` - - - -To use this function, your root key must have the `rbac.*.add_permission_to_key` and the `rbac.*.create_permission` permissions if you plan on creating permissions on the fly. - - -## Request - - - The id of the key - - - - The permissions you want to add to this key - - - -The id of the permission. Provide either id or name. If both are provided id is used. - - -Identify the permission via its name. Provide either id or name. If both are provided id is used. - - - Set to true to automatically create the permissions they do not exist yet. Only works when specifying name. - Autocreating permissions requires your root key to have the rbac.*.create_permission permission, otherwise the request will get rejected - - - - -## Response - - - - - - The id of the permission. This is used internally - - - - The name of the permission - - - diff --git a/apps/docs/libraries/ts/sdk/keys/add-roles.mdx b/apps/docs/libraries/ts/sdk/keys/add-roles.mdx deleted file mode 100644 index fbfb2a1aba..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/add-roles.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Add Roles" -description: "Add one or more roles to a key." ---- - - - -```ts -const { result, error } = await unkey.keys.addRoles({ - keyId: "key_123", - roles: [{ - "name": "domain.manager", - "create": true - }] -}) - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result) - -``` - - - - -```json -{ - "result": [ - { - "id": 'role_45TTRKT5Yh28M6Qj', - "name": 'domain.manager' - } - ] -} -``` - - - -To use this function, your root key must have the rbac.*.add_role_to_key and potentially the rbac.*.create_role permissions. - - -## Request - - - The id of the key - - - - The roles you want to add to this key - - - -The id of the role. Provide either id or name. If both are provided id is used. - - -Identify the role via its name. Provide either id or name. If both are provided id is used. - - - Set to true to automatically create the permissions they do not exist yet. Only works when specifying name. - Autocreating roles requires your root key to have the rbac.*.create_role permission, otherwise the request will get rejected - - - - -## Response - - - - - - The id of the role. This is used internally - - - - The name of the role - - - diff --git a/apps/docs/libraries/ts/sdk/keys/create.mdx b/apps/docs/libraries/ts/sdk/keys/create.mdx deleted file mode 100644 index 8f7a713ad8..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/create.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: "Create" -description: "Create an api key for your users" ---- - - - -```ts -const { result, error } = await unkey.keys.create({ - apiId: "api_123", - prefix: "xyz", - byteLength: 16, - externalId: "user_1234", - meta: { - hello: "world", - }, - expires: 1686941966471, - ratelimit: { - async: true, - duration: 1000, - limit: 10, - }, - remaining: 1000, - environment: "test", - name: "My Key", - permissions: ["email.test"], - roles: ["domain.manager"], - refill: { - interval: "monthly", - amount: 100, - refillDay: 15, - }, - enabled: true, -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result) - -``` - - - - -```json -{ - "result": { - "key": "xyz_AS5HDkXXPot2MMoPHD8jnL" - "keyId": "key_YALWkHZaA4neUa1JJoXTAw" - } -} -``` - - - - -## Request - - - Choose an `API` where this key should be created. - - - -To make it easier for your users to understand which product an api key belongs to, you can add prefix them. - -For example Stripe famously prefixes their customer ids with `cus_` or their api keys with `sk_live_`. - -The underscore is automtically added if you are defining a prefix, for example: `"prefix": "abc"` will result in a key like `abc_xxxxxxxxx` - - - - -The bytelength used to generate your key determines its entropy as well as its length. -Higher is better, but keys become longer and more annoying to handle. - -The default is `16 bytes`, or 2128 possible combinations - - - - - Deprecated, use externalId - - - Your user's Id. This will provide a link between Unkey and your customer record. - When validating a key, we will return this back to you, so you can clearly identify your user from their api key. - - - A way to easily identify the key by giving it a name. - - - -This is a place for dynamic meta data, anything that feels useful for you should go here - -Example: - -```json -{ - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z" -} -``` - - - -A list of roles that this key should have. If the role does not exist, an error is thrown - -Example: - -``` -["admin", "finance"] -``` - - -A list of permissions that this key should have. If the permission does not exist, an error is thrown - -Example: - -``` -["domains.create_record", "say_hello"] -``` - - - You can auto expire keys by providing a unix timestamp in milliseconds. - -Once keys expire they will automatically be deleted and are no longer valid. - - - - - -Unkey comes with per-key ratelimiting out of the box. - - - - - Either `true` (for fast rate limiting) or `false` (for consistent rate limiting). - -Read more [here](/apis/features/ratelimiting) - - - - Rate limiting duration in milliseconds. - - - - The total amount of burstable requests. - - - - How many tokens to refill during each `refillInterval` - - - Determines the speed at which tokens are refilled. - -In milliseconds - - - - - - - Add how many times a key can be used, for example 100. Read more - [here](/apis/features/remaining) - - - - -Unkey allows automatic refill on 'remaining' on a 'daily' or 'monthly' interval. - - - - - Either `daily` or `monthly`. - - - - - - The amount to refill 'remaining'. - -Read more [here](/apis/features/refill) - - - value from `1` to `31`. - - The day each month to refill 'remaining'. If no value is given, The 1st will be used as a default. - -Read more [here](/apis/features/refill) - - - - - Sets if the key is enabled or disabled. - - - -You may want to show keys again later. While we do not recommend this, we leave this option open for you. - -In addition to storing the key's hash, recoverable keys are stored in an encrypted vault, allowing you to retrieve and display the plaintext later. - -https://www.unkey.com/docs/security/recovering-keys for more information. - - - -Environments allow you to divide your keyspace. - -Some applications like Stripe, Clerk, WorkOS and others have a concept of "live" and "test" keys to -give the developer a way to develop their own application without the risk of modifying real world -resources. - -When you set an environment, we will return it back to you when validating the key, so you can -handle it correctly. - - - -## Response - - - - - - The newly created api key - - - - A unique identifier for this key. Use it later to update or revoke the key. - - - - diff --git a/apps/docs/libraries/ts/sdk/keys/delete.mdx b/apps/docs/libraries/ts/sdk/keys/delete.mdx deleted file mode 100644 index f16990f2d7..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/delete.mdx +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Delete" -description: "Delete an api key for your users" ---- - - - -```ts -const { result, error } = await unkey.keys.delete({ - keyId: "key_123", -}); -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result) -``` - - - -```json -{ - "result": {} -} -``` - - -## Request - - - The ID of the key you want to revoke. - - -## Response - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/keys/get.mdx b/apps/docs/libraries/ts/sdk/keys/get.mdx deleted file mode 100644 index 4ec43e795c..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/get.mdx +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: "Get" -description: "Get the configuration for an api key" ---- - - -```ts -const { result, error } = await unkey.keys.get({ keyId: "key_123" }); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result) -``` - - - - ```json - { - "result": { - "id": "key_123", - "start": "3ZHF3", - "apiId": "api_123", - "workspaceId": "ws_123", - "meta": {}, - "createdAt": 1747222842094, - "roles": [], - "permissions": [], - "enabled": true - } - } - ``` - - -## Request - - - The ID of the key you want to retrieve. - - -## Response - - - - - - - - The id of the key - - - -The first few characters of the key to visually identify it. - - - - The id of the workspace that owns the key - - - -The id of the api that this key is for - - - -The name of the key, give keys a name to easily identify their purpose - - - -The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this field back to you, so you know who is accessing your API. - - -Any additional metadata you want to store with the key - - - -The unix timestamp in milliseconds when the key was created - - - -The unix timestamp in milliseconds when the key was deleted. We don't delete the key outright, you can restore it later. - - -The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring. - - -The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit. - - -Unkey allows you to refill remaining verifications on a key on a regular interval. - - -Determines the rate at which verifications will be refilled. - -Available options: -- `daily`: Refills occur every day -- `monthly`: Refills occur once a month (see `refillDay` for specific day) - - -Resets `remaining` to this value every interval. - - - value from `1` to `31`. - - The day each month to refill 'remaining'. If no value is given, The 1st will be used as a default. - -Read more [here](/apis/features/refill) - - -The unix timestamp in miliseconds when the key was last refilled. - - - - - - - -Fast ratelimiting doesn't add latency, while consistent ratelimiting is more accurate. - - - -The total amount of burstable requests. - - -How many tokens to refill during each refillInterval. - - - - - -The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit. - - - All roles this key belongs to - - Example" - ``` - ["admin", "finance"] - ``` - - - - All permissions this key has - - Example" - ``` - ["domain.dns.create_record","finance.read_receipt"] - ``` - - - -Example: true - - -The key in plaintext - - - - Information about the associated identity, including its `id`, `externalId`, and `meta`. - - - The id of the identity - - -The external id of the identity - - - - - - - - - - - diff --git a/apps/docs/libraries/ts/sdk/keys/remove-permission.mdx b/apps/docs/libraries/ts/sdk/keys/remove-permission.mdx deleted file mode 100644 index 56fd755b54..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/remove-permission.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Remove Permissions" -description: "Remove one or more permissions from a key." ---- - - - - -```ts -const { result, error } = await unkey.keys.removePermissions({ - keyId: "key_123", - permissions: [ - { - name: "email.test", - }, - ], -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result) - -``` - - - - -```json -{ - "result": {} -} -``` - - - - - To use this function, your root key must have the `rbac.*.remove_permission_from_key` permission. - - -## Request - - - The id of the key - - - - The permissions you want to remove from this key - - - -The id of the permission. Provide either id or name. If both are provided id is used. - - -Identify the permission via its name. Provide either id or name. If both are provided id is used. - - - - -## Response - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/keys/remove-roles.mdx b/apps/docs/libraries/ts/sdk/keys/remove-roles.mdx deleted file mode 100644 index 81135863c4..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/remove-roles.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Remove Roles" -description: "Remove one or more roles from a key." ---- - - -```ts -const { result, error } = await unkey.keys.removeRoles({ - keyId: "key_123", - roles: [ - { - name: "domain.manager", - }, - ], -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result) - -``` - - - - -```json -{ "result": {} } -``` - - - - - To use this function, your root key must have the `rbac.*.remove_permission_from_key` permission. - - - -## Request - - - The id of the key - - - - The roles you want to remove from this key - - - -The id of the role. Provide either id or name. If both are provided id is used. - - -Identify the role via its name. Provide either id or name. If both are provided id is used. - - - - -## Response - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/keys/set-permission.mdx b/apps/docs/libraries/ts/sdk/keys/set-permission.mdx deleted file mode 100644 index b6fe7cc680..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/set-permission.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: "Set Permissions" -description: "Overwrite the permissions of a key with a new set of permissions." ---- - - -```ts -const { result, error } = await unkey.keys.setPermissions({ - keyId: "key_123", - permissions: [{ - "name": "email.test", - "create": true - }] -}) - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result) - -``` - - - - -```json -{ - "result": [ - { - "id": "role_45TTRKT5Yh28M6Qj", - "name": "domain.manager" - } - ] -} -``` - - - -To use this function, your root key must have the `rbac.*.add_permission_to_key` and the `rbac.*.create_permission` permissions if you plan on creating permissions on the fly. - - -## Request - - - The id of the key - - - - The permissions you want to add to this key - - - -The id of the permission. Provide either id or name. If both are provided id is used. - - -Identify the permission via its name. Provide either id or name. If both are provided id is used. - - - Set to true to automatically create the permissions they do not exist yet. Only works when specifying name. - Autocreating permissions requires your root key to have the rbac.*.create_permission permission, otherwise the request will get rejected - - - - -## Response - - - - - - The id of the permission. This is used internally - - - - The name of the permission - - - diff --git a/apps/docs/libraries/ts/sdk/keys/set-roles.mdx b/apps/docs/libraries/ts/sdk/keys/set-roles.mdx deleted file mode 100644 index f635afc9b6..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/set-roles.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Set Roles" -description: "Overwrite the roles of a key with a new set of roles." ---- - - - -```ts -const { result, error } = await unkey.keys.setRoles({ - keyId: "key_123", - roles: [{ - "name": "domain.manager", - "create": true - }] -}) - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result) - -``` - - - - -```json -{ - "result": [ - { - "id": "role_45TTRKT5Yh28M6Qj", - "name": "domain.manager" - } - ] -} -``` - - - -To use this function, your root key must have the rbac.*.add_role_to_key and potentially the rbac.*.create_role permissions. - - -## Request - - - The id of the key - - - - The roles you want to add to this key - - - -The id of the role. Provide either id or name. If both are provided id is used. - - -Identify the role via its name. Provide either id or name. If both are provided id is used. - - - Set to true to automatically create the permissions they do not exist yet. Only works when specifying name. - Autocreating roles requires your root key to have the rbac.*.create_role permission, otherwise the request will get rejected - - - - -## Response - - - - - - The id of the role. This is used internally - - - - The name of the role - - - diff --git a/apps/docs/libraries/ts/sdk/keys/update-remaining.mdx b/apps/docs/libraries/ts/sdk/keys/update-remaining.mdx deleted file mode 100644 index 741af9bebe..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/update-remaining.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Update Remaining" -description: "Update the remaining usage of a key." ---- - -```ts -const { result, error } =await unkey.keys.updateRemaining({ - keyId: "xyz_AS5HDkXXPot2MMoPHD8jnL", - value: 300, - op: "set" -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result) -``` - - - - -```json -{ - "result": { - "remaining": 300 - } -} -``` - - - -## Request - - - The ID of the key you want to update. - - - - Name of the operation to perform. The options are `increment`, `decrement` and `set`. - - - - The number to increment, decrement or set the remaining usage of a key. - -## Response - - - - - - The remaining usage of the key. - - - diff --git a/apps/docs/libraries/ts/sdk/keys/update.mdx b/apps/docs/libraries/ts/sdk/keys/update.mdx deleted file mode 100644 index e580b2aaa5..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/update.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Update" -description: "Update an api key for your users" ---- - -All json fields are optional, so you can update only the fields you need. -To delete a field, set it to `null`. - - - - -```ts -const { result, error } = await unkey.keys.update({ - keyId: "key_1233", - ownerId: "new owner", - remaining: 300, - refill: { - interval: "monthly", - amount: 100, - refillDay: 15, - }, - enabled: true -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result) -``` - - - - -```json -{ - "result": {} -} -``` - - - -## Request - - - The ID of the key you want to update. - - - - Update the name of the key. - - - - Update the owner id of the key. - - - - The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this back to you, so you know who is accessing your API. - Under the hood this upserts and connects an ìdentity for you. - To disconnect the key from an identity, set externalId: null. - - - - Update the metadata of a key. You will have to provide the full metadata - object, not just the fields you want to update. - - - - Update the expire time of a key. - -The expire time is a unix timestamp in milliseconds. - - - - - -Unkey comes with per-key ratelimiting out of the box. - - - - - Either `fast` or `consistent`. - -Read more [here](/apis/features/ratelimiting) - - - - The total amount of burstable requests. - - - - How many tokens to refill during each `refillInterval` - - - Determines the speed at which tokens are refilled. - -In milliseconds - - - - - - - Update the remaining usage of a key. - - - - -Unkey allows automatic refill on 'remaining' on a 'daily' or 'monthly' interval. - - - - - Either `daily` or `monthly`. - - - - - - The amount to refill 'remaining'. - -Read more [here](/apis/features/refill) - - - value from `1` to `31`. - - The day each month to refill 'remaining'. If no value is given, The 1st will be used as a default. - -Read more [here](/apis/features/refill) - - - - Sets if the key is enabled or disabled. - - - - -A list of roles that this key should have. If the role does not exist, an error is thrown - -Example: - -``` -["admin", "finance"] -``` - - -A list of permissions that this key should have. If the permission does not exist, an error is thrown - -Example: - -``` -["domains.create_record", "say_hello"] -``` - - - -## Response - - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/keys/verifications.mdx b/apps/docs/libraries/ts/sdk/keys/verifications.mdx deleted file mode 100644 index 1d9279d435..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/verifications.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "Verifications" -description: "Get usage information about your API keys" ---- - - This is deprecated, please use the `analytics.getVerifications` function instead. - - - -```ts -const { result, error } = await unkey.keys.getVerifications({ keyId: "key_123" }); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result) -``` - - - -```json -{ - "verifications": [ - { - "time": 1620000000000, - "success": 100, - "rateLimited": 0, - "usageExceeded": 0 - }, - { - "time": 1640000000000, - "success": 142, - "rateLimited": 11, - "usageExceeded": 20 - }, - ] -} -``` - - - -## Request - - -Either `ownerId` or `keyId` is required. Not both. - - - - The ID of the key you want to check. - - - - - The `ownerId` associated with one or more keys you want to check. - - - - - The unix timestamp in milliseconds to start the query from. Defaults to 30 days ago. - - - - The unix timestamp in milliseconds to end the query at. Defaults to now. - - - - - The granularity of the data. Only `day` is supported at this time. - - - -## Response - - - - - - - - - - -The timestamp of the usage data - - - -The number of successful requests. - - - -The number of requests that were rate limited - - - -The number of requests that exceeded the usage limit. - - - - - - - - diff --git a/apps/docs/libraries/ts/sdk/keys/verify.mdx b/apps/docs/libraries/ts/sdk/keys/verify.mdx deleted file mode 100644 index 4a08cbd52d..0000000000 --- a/apps/docs/libraries/ts/sdk/keys/verify.mdx +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: "Verify" -description: "Verify a key" ---- - - -```ts -import { verifyKey } from "@unkey/api"; - -const { result, error } = await verifyKey({ key: "key_123", apiId: "api_123" }); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -if (!result.valid) { - // do not grant access - return; -} - -// process request -console.log(result); -``` - - - -```json -{ - "result": { - "keyId": "key_1234", - "valid": true, - "name": "Customer X", - "ownerId": "user_123", - "meta": { - "roles": [ - "admin", - "user" - ], - "stripeCustomerId": "cus_1234" - }, - "expires": 123, - "ratelimit": { - "limit": 10, - "remaining": 9, - "reset": 3600000 - }, - "remaining": 1000, - "code": "VALID", - "enabled": true, - "permissions": [ - "dns.record.update", - "dns.record.delete" - ], - "environment": "test", - "identity": { - "id": "", - "externalId": "", - "meta": {} - } -} -} -``` - - -## Request - - - The key you want to verify. - - - - - The api this key belongs to. This will be required soon. - - - - - Override the behavior of the ratelimit for this verification. - - - The cost of this verification. This will be subtracted from the ratelimit. - Use this if you need to ratelimit based on what the user is trying to access. For example, you may want to ratelimit a user based on the tokens they are using in the context of LLM APIs. - - - - - - - -## Response - - - - - - The id of the key you are verifying. - - - - Whether or not this key is valid and has passed the ratelimit. If `false` you - should not grant access to whatever the user is requesting - - - - The name of the key you are verifying. - - - - If you have set an `ownerId` on this key it is returned here. You can use this - to clearly authenticate a user in your system. - - - -This is the `meta` data you have set when creating the key. - -Example: - -```json -{ - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z" -} -``` - - - - - The unix timestamp in milliseconds indicating when this key expires. - - - - The current ratelimit state. - - - - - Current limit after this verification. - - - - Remaining limit inside this burst window. - - - - - A unix timestamp in millisecond when the ratelimit gets refilled the next time. - - - - - - - - Shows how many more times this key may be verified before being invalidated. - Only applies to keys where you have set a `remaining` count. - - - - If the key is invalid this field will be set to the reason why it is invalid. - - Possible values are: - - `NOT_FOUND` - The key does not exist - - `FORBIDDEN` - You are not allowed to verify this key. For example because of additional security - checks like `IP whitelists` - - `USAGE_EXCEEDED` - The key has been used up and is no longer valid - - `RATE_LIMITED` - The verification has been blocked due to ratelimiting - - `DISABLED` - The key is disabled - - `EXPIRED` - The key has expired - - - - - Shows if the key is enabled or disabled. - - - - - A list of all the permissions this key is connected to. - - - - The environment of the key, this is what what you set when you crated the key - - - -The associated identity of this key. - - - - - - A free form JSON object. You can store any data you want here. As long as its properly formatted JSON. - - - - - - - - diff --git a/apps/docs/libraries/ts/sdk/migrations/migrate-to-unkey.mdx b/apps/docs/libraries/ts/sdk/migrations/migrate-to-unkey.mdx deleted file mode 100644 index 9720603d43..0000000000 --- a/apps/docs/libraries/ts/sdk/migrations/migrate-to-unkey.mdx +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: "Migrate key to Unkey" -description: "Add existing keys to unkey by specifying the key hash and other settings" ---- - - - -```ts -const { result, error } = await unkey.migrations.createKeys([ - { - apiId: "api_123", - prefix: "xyz", - byteLength: 16, - externalId: "user_1234", - plaintext: "prod_plaintext", - }, - { - apiId: "api_123", - prefix: "xyz", - byteLength: 16, - externalId: "user_5678", - hash: { - value: - "00c0116331ffb5cc407f8f64ad58decc8b9d2e8a7b42746ba28e96ecb22b748c", - variant: "sha256_base64", - }, - }, -]); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "keyIds": [ - "key_123", - "key_456" - ] -} -``` - - - - -## Request - - - Choose an `API` where this key should be created. - - - -To make it easier for your users to understand which product an api key belongs to, you can add prefix them. - -For example Stripe famously prefixes their customer ids with `cus_` or their api keys with `sk_live_`. - -The underscore is automtically added if you are defining a prefix, for example: `"prefix": "abc"` will result in a key like `abc_xxxxxxxxx` - - - - -The bytelength used to generate your key determines its entropy as well as its length. -Higher is better, but keys become longer and more annoying to handle. - -The default is `16 bytes`, or 2128 possible combinations - - - - - Deprecated, use externalId - - - Your user's Id. This will provide a link between Unkey and your customer record. - When validating a key, we will return this back to you, so you can clearly identify your user from their api key. - - - A way to easily identify the key by giving it a name. - - - - - The raw key in plaintext. If provided, unkey encrypts this value and stores it securely. Provide either hash or plaintext - - - Provide either hash or plaintext - - - The hashed and encoded key - - - The algorithm for hashing and encoding, currently only sha256 and base64 are supported - - Available options: `sha256_base64` - - - - - - -This is a place for dynamic meta data, anything that feels useful for you should go here - -Example: - -```json -{ - "billingTier": "PRO", - "trialEnds": "2023-06-16T17:16:37.161Z" -} -``` - - - -A list of roles that this key should have. If the role does not exist, an error is thrown - -Example: - -``` -["admin", "finance"] -``` - - -A list of permissions that this key should have. If the permission does not exist, an error is thrown - -Example: - -``` -["domains.create_record", "say_hello"] -``` - - - You can auto expire keys by providing a unix timestamp in milliseconds. - -Once keys expire they will automatically be deleted and are no longer valid. - - - - - -Unkey comes with per-key ratelimiting out of the box. - - - - - Either `true` (for fast rate limiting) or `false` (for consistent rate limiting). - -Read more [here](/apis/features/ratelimiting) - - - - Rate limiting duration in milliseconds. - - - - The total amount of burstable requests. - - - - How many tokens to refill during each `refillInterval` - - - Determines the speed at which tokens are refilled. - -In milliseconds - - - - - - - Add how many times a key can be used, for example 100. Read more - [here](/apis/features/remaining) - - - - -Unkey allows automatic refill on 'remaining' on a 'daily' or 'monthly' interval. - - - - - Either `daily` or `monthly`. - - - - - - The amount to refill 'remaining'. - -Read more [here](/apis/features/refill) - - - value from `1` to `31`. - - The day each month to refill 'remaining'. If no value is given, The 1st will be used as a default. - -Read more [here](/apis/features/refill) - - - - - Sets if the key is enabled or disabled. - - - -You may want to show keys again later. While we do not recommend this, we leave this option open for you. - -In addition to storing the key's hash, recoverable keys are stored in an encrypted vault, allowing you to retrieve and display the plaintext later. - -https://www.unkey.com/docs/security/recovering-keys for more information. - - - -Environments allow you to divide your keyspace. - -Some applications like Stripe, Clerk, WorkOS and others have a concept of "live" and "test" keys to -give the developer a way to develop their own application without the risk of modifying real world -resources. - -When you set an environment, we will return it back to you when validating the key, so you can -handle it correctly. - - - -## Response - - - - - - The newly created api key - - - - A unique identifier for this key. Use it later to update or revoke the key. - - - - diff --git a/apps/docs/libraries/ts/sdk/overview.mdx b/apps/docs/libraries/ts/sdk/overview.mdx deleted file mode 100644 index 1c11d9b67a..0000000000 --- a/apps/docs/libraries/ts/sdk/overview.mdx +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: "Overview" -description: "Typescript client for unkey" ---- - - -If you prefer a typed experience over calling http endpoints directly, you can use our sdk `@unkey/api`. - -## Install - - - - ```bash npm - npm install @unkey/api - ``` - - ```bash pnpm - pnpm add @unkey/api - ``` - - ```bash yarn - yarn add @unkey/api - ``` - - ```bash bun - bun install @unkey/api - ``` - - -## Unkey Root Key - -When creating, revoking or updating resources, you will need your root key — you can create a new one in the [settings](https://app.unkey.com/settings/root-keys). -Afterwards you need to provide it to the client: - -```ts -import { Unkey } from "@unkey/api"; - -const unkey = new Unkey({ rootKey: "" }); -``` - -Always keep your root key safe and reset it `if` you suspect it has been compromised. - -## Response format - -Because forgetting to handle thrown errors properly in javascript is often forgotten, we have decided to explicitly return errors to be handled. Fortunately typescript helps us here and everything is typesafe. - -Every method returns either an `error` or a `result` field, never both and never none. - - -```ts Success -{ - result: T // the result depends on what method you called -} -``` - -```ts Error -{ - error: { - // A machine readable error code - code: ErrorCode; - - // A link to our documentation explaining this error in more detail - docs: string; - - // A human readable short explanation - message: string; - - // The request id for easy support lookup - requestId: string; - } -} -``` - - - -## Checking for errors - -To check for errors you use the `error` property, our errors are easy to read and provide a link to our documentation for more information. - -```ts -import { verifyKey } from "@unkey/api"; - -const { result, error } = await verifyKey("key_123"); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -if (!result.valid) { - // do not grant access - return; -} - -// process request -console.log(result); -``` - - -## Options - -The constructor accepts some options to customize the behavior: - - -### Base Url - -Run all requests against your own instance of unkey hosted on your own infrastructure. - - -```ts -const unkey = new Unkey({ - //... - baseUrl: "https://my.domain" -}) -``` - - -### Retries - -By default the client will retry on network errors, you can customize this behavior: - - - - - How often to retry - - - A function that returns how many milliseconds to wait until the next attempt is made. - - - - -```ts -const unkey = new Unkey({ - // ... - retry: { - attempts: 3, - backoff: (retryCount) => retryCount * 1000 - } -}) -``` - -### Cache - -Configure the `fetch` cache behavior. - - -As of October 2023, the `cache` option is not yet implemented in cloudflare workers and will throw an error if used. - - - - Available options are: `default`, `force-cache`, `no-cache`, `no-store`, `only-if-cached` or `reload`. - - -```ts -const unkey = new Unkey({ - // ... - cache: "no-cache" -}) -``` - -### Disable telemetry - -By default, Unkey collects anonymous telemetry data to help us understand which versions of our SDK is being used, and in which environment. - -If you wish to disable this, you can do so by passing a boolean flag to the constructor: - -```ts -const unkey = new Unkey({ - disableTelemetry: true -}) -``` diff --git a/apps/docs/libraries/ts/sdk/permissions/create-permission.mdx b/apps/docs/libraries/ts/sdk/permissions/create-permission.mdx deleted file mode 100644 index b4c535b667..0000000000 --- a/apps/docs/libraries/ts/sdk/permissions/create-permission.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Create A Permission" -description: "Create a new permission to use with Unkey." ---- - - - -```ts -const { result, error } = await unkey.permissions.createPermission({ - name: "record.write", - description: - "record.write can create new dns records for our domains.", -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "result": { - "permissionId": "perm_123" - } -} -``` - - - - -To use this function, your root key must have the `rbac.*.create_permission` permission. - - -## Request - - - The unique name of your permission. - - Required string length: 3 - 256 - - Example: `"record.write"` - - - - Explain what this permission does. This is just for your team, your users will not see this. - - Required string length: 3 - 256 - - Example:`"record.write can create new dns records for our domains."` - - -## Response - - - The id of the permission. This is used internally - - Example: `"perm_123"` - - diff --git a/apps/docs/libraries/ts/sdk/permissions/create-role.mdx b/apps/docs/libraries/ts/sdk/permissions/create-role.mdx deleted file mode 100644 index 4c40872a0f..0000000000 --- a/apps/docs/libraries/ts/sdk/permissions/create-role.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Create A Role" -description: "Create a new role to use with Unkey" ---- - - - -```ts -const { result, error } = await unkey.permissions.createRole({ - name: "dns.records.manager", - description: - "dns.records.manager can read and write dns records for our domains", -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - -```json -{ - "result": { - "roleId": "role_45TTRKT5Yh28M6Qj" - } -} -``` - - - - -To use this function, your root key must have the `rbac.*.create_role` - - -## Request - - - The unique name of your role. - - Required string length: 3 - 256 - - Example: `"dns.records.manager"` - - - - Explain what this role does. This is just for your team, your users will not see this. - - Required string length: 3 - 256 - - Example:`"dns.records.manager can read and write dns records for our domains."` - - -## Response - - - The id of the role. This is used internally - - Example: `"role_123"` - - diff --git a/apps/docs/libraries/ts/sdk/permissions/delete-permission.mdx b/apps/docs/libraries/ts/sdk/permissions/delete-permission.mdx deleted file mode 100644 index ace2ffea20..0000000000 --- a/apps/docs/libraries/ts/sdk/permissions/delete-permission.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Delete A Permission" -description: "Delete a permission from the Unkey system" ---- - - - -```ts -const { result, error } = await unkey.permissions.deletePermission({ - permissionId: "perm_1234", -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result); -``` - - - - -```json -{ - "result": {} -} -``` - - - - -To use this function, your root key must have the `rbac.*.delete_permission` - - -## Request - - - The id of the permission to delete - - Example: `"perm_123"` - - -## Response - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/permissions/delete-role.mdx b/apps/docs/libraries/ts/sdk/permissions/delete-role.mdx deleted file mode 100644 index b34e1a73fe..0000000000 --- a/apps/docs/libraries/ts/sdk/permissions/delete-role.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Delete A Role" -description: "Delete a role from the Unkey system" ---- - - - -```ts -const { result, error } = await unkey.permissions.deleteRole({ - roleId: "role_45TTRKT5Yh28M6Qj", -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result); -``` - - - - -```json -{ - "result": {} -} -``` - - - - -To use this function, your root key must have the `rbac.*.delete_role` - - -## Request - - - The id of the role to delete - - Example: `"role_123"` - - -## Response - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/permissions/get-permission.mdx b/apps/docs/libraries/ts/sdk/permissions/get-permission.mdx deleted file mode 100644 index b18764914b..0000000000 --- a/apps/docs/libraries/ts/sdk/permissions/get-permission.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Get A Permission" -description: "Retrieve a permission from Unkey" ---- - - - -```ts -const { result, error } = await unkey.permissions.getPermission({ - permissionId: "perm_123", -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result); -} -``` - - - - -```json -{ - "result": { - "id": "perm_123", - "name": "domain.record.manager", - "description": "Can manage dns records" - } -} -``` - - - -To use this function, your root key must have the `rbac.*.read_permission` - - -## Request - - - The id of the permission to fetch - - Minimum length: `1` - - Example: `"perm_123"` - - -## Response - - - The id of the permission. This is used internally - - Example: `"perm_123"` - - - - - The unique name of your permission. - - Example: `"domain.record.manager"` - - - - The description of what this permission does. This is just for your team, your users will not see this. - - Example:`"Can manage dns records."` - diff --git a/apps/docs/libraries/ts/sdk/permissions/get-role.mdx b/apps/docs/libraries/ts/sdk/permissions/get-role.mdx deleted file mode 100644 index 33fdc573f4..0000000000 --- a/apps/docs/libraries/ts/sdk/permissions/get-role.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Get A Role" -description: "Retrieve a role from Unkey" ---- - - - -```ts -const { result, error } = await unkey.permissions.getRole({ - roleId: "role_45TTRKT5Yh28M6Qj", -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} -console.log(result); -``` - - - - -```json -{ - "result": { - "id": "role_45TTRKT5Yh28M6Qj", - "name": "domain.record.manager", - "description": "Can manage dns records" - } -} -``` - - - -To use this function, your root key must have the `rbac.*.read_role` - - -## Request - - - The id of the role to fetch - - Minimum length: `1` - - Example: `"role_123"` - - -## Response - - - The id of the role. This is used internally - - Example: `"role_123"` - - - - - The unique name of your role. - - Example: `"dns.records.manager"` - - - - The description of what this role does. This is just for your team, your users will not see this. - - - Example:`"dns.records.manager can read and write dns records for our domains."` - diff --git a/apps/docs/libraries/ts/sdk/ratelimits/limit.mdx b/apps/docs/libraries/ts/sdk/ratelimits/limit.mdx deleted file mode 100644 index 2f1028bd82..0000000000 --- a/apps/docs/libraries/ts/sdk/ratelimits/limit.mdx +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Limit" -description: "Serverless ratelimiting" ---- - - - -```ts -const {result, error} = await unkey.ratelimits.limit({ - duration: 600, - identifier: "userId", - limit: 2000, - namespace: "test" - }) - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -if(!result.success){ - console.log("This is blocked do some logic") - return; -} - -console.log(result); - -``` - - - - -```json -{ - "result": { - "success": true, - "limit": 2000, - "reset": 1630000000000, - "remaining": 300 - } -} -``` - - - - -We have a dedicated package for ratelimiting in serverless functions. It's built with Cloudflare workers and Durable Objects to orchestrate low latency ratelimiting at the edge, without sacrificing consistency. - -Check out the documentation for the [`@unkey/ratelimit` package](/libraries/ts/ratelimit). - -## Request - - -How many requests may pass in the given duration. - - -How long the window should be. - -Either a type string literal like `60s`, `20m` or plain milliseconds. - - - - A unique identifier for the request. This can be a user id, an IP address or a session id. - - - The route or resource of what is being ratelimited for example `trpc.user.update` - - -Expensive requests may use up more resources. You can specify a cost to the request and - we'll deduct this many tokens in the current window. If there are not enough tokens left, - the request is denied. - -**Example:** - - 1. You have a limit of 10 requests per second you already used 4 of them in the current - window. - - 2. Now a new request comes in with a higher cost: - ```ts - const res = await rl.limit("identifier", { cost: 4 }) - ``` - - 3. The request passes and the current limit is now at `8` - - 4. The same request happens again, but would not be rejected, because it would exceed the - limit in the current window: `8 + 4 > 10` - - - - - -Do not wait for a response from the origin. Faster but less accurate. - -We observe a 97%+ accuracy when using `async` mode with significantly lower latency. - - - -Record arbitrary data about this request. This does not affect the limit itself but can help you debug later. - - - -Specify which resources this request would access and we'll create a papertrail for you. - -See [app.unkey.com/audit](https://app.unkey.com/audit) for details. - -## Response - - - - - -Whether the request may pass(true) or exceeded the limit(false). - - -Maximum number of requests allowed within a window. - - -How many requests the user has left within the current window. - - -Unix timestamp in milliseconds when the limits are reset. - - - diff --git a/apps/docs/libraries/ts/sdk/ratelimits/overrides/delete-override.mdx b/apps/docs/libraries/ts/sdk/ratelimits/overrides/delete-override.mdx deleted file mode 100644 index 69ecaef174..0000000000 --- a/apps/docs/libraries/ts/sdk/ratelimits/overrides/delete-override.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "Delete Override" -description: "Deletes an override" ---- - - - -```ts -const {result,error} = await unkey.ratelimits.deleteOverride({ - identifier: "user_123", - namespaceName: "email.outbound", -}) - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - - ```json - { - "result": {} - } - ``` - - -## Request - -Identifier of your user, this can be their userId, an email, an ip or anything else. Wildcards ( * ) can be used to match multiple identifiers, More info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - - -Either `namespaceId` or `namespaceName` is required. Not both. - - - -The id of the namespace. Either namespaceId or namespaceName must be provided - - - -Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes. Wildcards can also be used, more info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - - -## Response - - `{}` - diff --git a/apps/docs/libraries/ts/sdk/ratelimits/overrides/get-override.mdx b/apps/docs/libraries/ts/sdk/ratelimits/overrides/get-override.mdx deleted file mode 100644 index 36ced387b4..0000000000 --- a/apps/docs/libraries/ts/sdk/ratelimits/overrides/get-override.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Get Override" -description: "Gets a ratelimit override" ---- - - -```ts -const { result, error } = await unkey.ratelimits.getOverride({ - identifier:"user.example", - namespaceName: "email.outbound" -}); -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - -```json -{ - "result": { - "id": "rlor_4567", - "identifier": "user.example", - "limit": 10, - "duration": 60000, - "async": false - } -} -``` - - -## Request - -Identifier of your user, this can be their userId, an email, an ip or anything else. Wildcards ( * ) can be used to match multiple identifiers, More info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - - -Either `namespaceId` or `namespaceName` is required. Not both. - - - -The id of the namespace. Either namespaceId or namespaceName must be provided - - - -Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes. Wildcards can also be used, more info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - - -## Response - - - - - -Identifier of the override requested - - - -Identifier of your user, this can be their userId, an email, an ip or anything else. Wildcards ( * ) can be used to match multiple identifiers, More info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - - -How many requests may pass in a given window. - - - -The window duration in milliseconds. - - - -Async will return a response immediately, lowering latency at the cost of accuracy. - - - diff --git a/apps/docs/libraries/ts/sdk/ratelimits/overrides/list-overrides.mdx b/apps/docs/libraries/ts/sdk/ratelimits/overrides/list-overrides.mdx deleted file mode 100644 index 887145e8ec..0000000000 --- a/apps/docs/libraries/ts/sdk/ratelimits/overrides/list-overrides.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "List Overrides" -description: "Lists all overrides" ---- - - - -```ts -const { result ,error } = await unkey.ratelimits.listOverrides({ - namespaceName: "email.outbound" -}); - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - -```json -{ - "result": { - "overrides": [ - { - "id": "rlor_1234", - "identifier": "customer_123", - "limit": 10, - "duration": 50000, - "async": false - } - ], - total: 1, - cursor: 'eyJrZXkiOiJrZXlfMTIzNCJ9' - } -} -``` - - - -## Request - - -Either `namespaceId` or `namespaceName` is required. Not both. - - - -The id of the namespace. Either namespaceId or namespaceName must be provided - - - -Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes. Wildcards can also be used, more info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - -## Response - - - - - - - - -Identifier of the override requested - - - -Identifier of your user, this can be their userId, an email, an ip or anything else. Wildcards ( * ) can be used to match multiple identifiers, More info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - - -How many requests may pass in a given window. - - - -The window duration in milliseconds. - - - -Async will return a response immediately, lowering latency at the cost of accuracy. - - - - - - -The total number of overrides - - -The cursor to use for pagination - - - - diff --git a/apps/docs/libraries/ts/sdk/ratelimits/overrides/set-override.mdx b/apps/docs/libraries/ts/sdk/ratelimits/overrides/set-override.mdx deleted file mode 100644 index 9656e950b3..0000000000 --- a/apps/docs/libraries/ts/sdk/ratelimits/overrides/set-override.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Set Override" -description: "Sets an override for a ratelimit" ---- - -## Request - - - -Identifier of your user, this can be their userId, an email, an ip or anything else. Wildcards ( * ) can be used to match multiple identifiers, More info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - - -How many requests may pass in a given window. - - - -The window duration in milliseconds. - - - -Either `namespaceId` or `namespaceName` is required. Not both. - - - -The id of the namespace. Either namespaceId or namespaceName must be provided - - - -Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes. Wildcards can also be used, more info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - - - -Async will return a response immediately, lowering latency at the cost of accuracy. - - - -## Response - - - - - The id of the override that was set. - - - - - -```ts -const { result, error } = await unkey.ratelimits.setOverride({ - identifier: "user_123", - limit: 10, - duration: 60000, - namespaceId: "rlns_1234", - async: true -}) - -if (error) { - // handle potential network or bad request error - // a link to our docs will be in the `error.docs` field - console.error(error.message); - return; -} - -console.log(result); -``` - - - -```json -{ - "result": { - "overrideId": "rlor_12345" - } -} -``` - -